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-2001, All Rights Reserved">
   7 <META NAME="docnumber" CONTENT="CUPS-SPM-1.1.9">
   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.9<BR>
  26 Easy Software Products<BR>
  27 Copyright 1997-2001, 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 1.1.9.</P>
1077 <H2><A NAME="1_1">System Overview</A></H2>
1078 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
1079  systems. It has been developed by<A HREF="http://www.easysw.com"> Easy
1080  Software Products</A> to promote a standard printing solution for all
1081  UNIX vendors and users. CUPS provides the System V and Berkeley
1082  command-line interfaces.</P>
1083 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
1084  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
1085  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
1086  also supported with reduced functionality. CUPS adds network printer
1087  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
1088  options to support real-world printing under UNIX.</P>
1089 <P>CUPS also includes a customized version of GNU Ghostscript (currently
1090  based off GNU Ghostscript 5.50) and an image file RIP that are used to
1091  support non-PostScript printers. Sample drivers for HP and EPSON
1092  printers are included that use these filters.</P>
1093
1094 <!-- NEED 2in -->
1095 <H2><A NAME="1_2">Document Overview</A></H2>
1096 <P>This software programmers manual is organized into the following
1097  sections:</P>
1098 <UL>
1099 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI>
1100 <LI><A HREF="#CUPS_API">2 - The CUPS API</A></LI>
1101 <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></LI>
1102 <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></LI>
1103 <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></LI>
1104 <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI>
1105 <LI><A HREF="#CONSTANTS">B - Constants</A></LI>
1106 <LI><A HREF="#STRUCTURES">C - Structures</A></LI>
1107 <LI><A HREF="#FUNCTIONS">D - Functions</A></LI>
1108 </UL>
1109 <H2><A NAME="1_3">Notation Conventions</A></H2>
1110 <P>Various font and syntax conventions are used in this guide. Examples
1111  and their meanings and uses are explained below:
1112 <CENTER>
1113 <TABLE WIDTH="80%">
1114 <TR><TH>Example</TH><TD>&nbsp;&nbsp;&nbsp;</TD><TH>Description</TH></TR>
1115 <TR><TD>&nbsp;</TD></TR>
1116 <TR VALIGN="TOP"><TD><CODE>lpstat</CODE>
1117 <BR> <CODE>lpstat(1)</CODE></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>The names of commands;
1118  the first mention of a command or function in a chapter is followed by
1119  a manual page section number.</TD></TR>
1120 <TR><TD>&nbsp;</TD></TR>
1121 <TR VALIGN="TOP"><TD><VAR>/var</VAR>
1122 <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>
1123 File and directory names.</TD></TR>
1124 <TR><TD>&nbsp;</TD></TR>
1125 <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD>
1126 &nbsp;&nbsp;&nbsp;</TD><TD>Screen output.</TD></TR>
1127 <TR><TD>&nbsp;</TD></TR>
1128 <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD>
1129 &nbsp;&nbsp;&nbsp;</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
1130  in ALL CAPS.</TD></TR>
1131 <TR><TD>&nbsp;</TD></TR>
1132 <TR VALIGN="TOP"><TD>12.3</TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>Numbers in the text are
1133  written using the period (.) to indicate the decimal point.</TD></TR>
1134 </TABLE>
1135 </CENTER>
1136
1137 <!-- NEED 3in -->
1138 </P>
1139 <H2><A NAME="1_4">Abbreviations</A></H2>
1140  The following abbreviations are used throughout this manual:
1141 <UL>
1142 <DL>
1143 <DT>kb</DT>
1144 <DD>Kilobytes, or 1024 bytes
1145 <BR>&nbsp;</DD>
1146 <DT>Mb</DT>
1147 <DD>Megabytes, or 1048576 bytes
1148 <BR>&nbsp;</DD>
1149 <DT>Gb</DT>
1150 <DD>Gigabytes, or 1073741824 bytes
1151 <BR>&nbsp;</DD>
1152 </DL>
1153 </UL>
1154 <H2><A NAME="1_5">Other References</A></H2>
1155 <UL>
1156 <DL>
1157 <DT>CUPS Software Administrators Manual</DT>
1158 <DD>An administration guide for the CUPS software.
1159 <BR>&nbsp;</DD>
1160 <DT>CUPS Software Users Manual</DT>
1161 <DD>An end-user guide for using the CUPS software.
1162 <BR>&nbsp;</DD>
1163 </DL>
1164 </UL>
1165 <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1>
1166 <P>This chapter provides an overview of how the Common UNIX Printing
1167  System works.</P>
1168 <H2><A NAME="2_1">The Printing Problem</A></H2>
1169 <P>For years<I> the printing problem</I> has plagued UNIX. Unlike
1170  Microsoft&reg; Windows&reg; or Mac OS, UNIX has no standard interface or system
1171  in place for supporting printers. Among the solutions currently
1172  available, the Berkeley and System V printing systems are the most
1173  prevalent.</P>
1174 <P>These printing systems support line printers (text only) or
1175  PostScript printers (text and graphics), and with some coaxing they can
1176  be made to support a full range of printers and file formats. However,
1177  because each varient of the UNIX operating system uses a different
1178  printing system than the next developing printer drivers for a wide
1179  range of printers and operating systems is extremely difficult. That
1180  combined with the limited volume of customers for each UNIX varient has
1181  forced most printer vendors to give up supporting UNIX entirely.</P>
1182 <P>CUPS is designed to eliminate<I> the printing problem</I>. One common
1183  printing system can be used by all UNIX varients to support the
1184  printing needs of users. Printer vendors can use its modular filter
1185  interface to develop a single driver program that supports a wide range
1186  of file formats with little or no effort. Since CUPS provides both the
1187  System V and Berkeley printing commands, users (and applications) can
1188  reap the benefits of this new technology with no changes.</P>
1189 <H2><A NAME="2_2">The Technology</A></H2>
1190 <P>CUPS is based upon an emerging Internet standard called the Internet
1191  Printing Protocol. IPP has been embraced by dozens of printer and
1192  printer server manufacturers and is supported by Microsoft Windows
1193  2000.</P>
1194 <P>IPP defines a standard protocol for printing as well as managing
1195  print jobs and printer options like media size, resolution, and so
1196  forth. Like all IP-based protocols, IPP can be used locally or over the
1197  Internet to printers hundreds or thousands of miles away. Unlike other
1198  protocols, however, IPP also supports access control, authentication,
1199  and encryption, making it a much more capable and secure printing
1200  solution than older ones.</P>
1201 <P>IPP is layered on top of the Hyper-Text Transport Protocol (&quot;HTTP&quot;)
1202  which is the basis of web servers on the Internet. This allows users to
1203  view documentation, check status information on a printer or server,
1204  and manage their printers, classes, and jobs using their web browser.</P>
1205 <P>CUPS provides a complete IPP/1.1 based printing system that provides
1206  Basic, Digest, and local certificate authentication and user, domain,
1207  or IP-based access control. TLS encryption will be available in future
1208  versions of CUPS.</P>
1209 <H2><A NAME="2_3">Jobs</A></H2>
1210 <P>Each file or set of files that is submitted for printing is called a<I>
1211  job</I>. Jobs are identified by a unique number starting at 1 and are
1212  assigned to a particular destination, usually a printer. Jobs can also
1213  have options associated with them such as media size, number of copies,
1214  and priority.</P>
1215 <H2><A NAME="2_4">Classes</A></H2>
1216 <P>CUPS supports collections of printers known as<I> classes</I>. Jobs
1217  sent to a class are forwarded to the first available printer in the
1218  class.</P>
1219 <H2><A NAME="2_5">Filters</A></H2>
1220 <P>Filters allow a user or application to print many types of files
1221  without extra effort. Print jobs sent to a CUPS server are filtered
1222  before sending them to a printer. Some filters convert job files to
1223  different formats that the printer can understand. Others perform page
1224  selection and ordering tasks.</P>
1225 <P>CUPS provides filters for printing many types of image files, HP-GL/2
1226  files, PDF files, and text files. CUPS also supplies PostScript and
1227  image file Raster Image Processor (&quot;RIP&quot;) filters that convert
1228  PostScript or image files into bitmaps that can be sent to a raster
1229  printer.</P>
1230 <H2><A NAME="2_6">Backends</A></H2>
1231 <P>Backends perform the most important task of all - they send the
1232  filtered print data to the printer.</P>
1233 <P>CUPS provides backends for printing over parallel, serial, and USB
1234  ports, and over the network via the IPP, JetDirect (AppSocket), and
1235  Line Printer Daemon (&quot;LPD&quot;) protocols. Additional backends are
1236  available in network service packages such as the SMB backend included
1237  with the popular SAMBA software.</P>
1238 <P>Backends are also used to determine the available devices. On startup
1239  each backend is asked for a list of devices it supports, and any
1240  information that is available. This allows the parallel backend to tell
1241  CUPS that an EPSON Stylus Color 600 printer is attached to parallel
1242  port 1, for example.</P>
1243 <H2><A NAME="2_7">Printer Drivers</A></H2>
1244 <P>Printer drivers in CUPS consist of one of more filters specific to a
1245  printer. CUPS includes sample printer drivers for Hewlett-Packard
1246  LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
1247  and Stylus Photo printers. While these drivers do not generate optimal
1248  output for the different printer models, they do provide basic printing
1249  and demonstrate how you can write your own printer drivers and
1250  incorporate them into CUPS.</P>
1251 <H2><A NAME="2_8">Networking</A></H2>
1252 <P>Printers and classes on the local system are automatically shared
1253  with other systems on the network. This allows you to setup one system
1254  to print to a printer and use this system as a printer server or spool
1255  host for all of the others. Users may then select a local printer by
1256  name or a remote printer using &quot;name@server&quot;.</P>
1257 <P>CUPS also provides<I> implicit classes</I>, which are collections of
1258  printers and/or classes with the same name. This allows you to setup
1259  multiple servers pointing to the same physical network printer, for
1260  example, so that you aren't relying on a single system for printing.
1261  Because this also works with printer classes, you can setup multiple
1262  servers and printers and never worry about a single point of failure
1263  unless all of the printers and servers go down!</P>
1264 <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
1265 <P>This chapter describes the CUPS Application Programmers Interface
1266  (&quot;API&quot;).</P>
1267 <H2><A NAME="3_1">The CUPS API Library</A></H2>
1268 <P>The CUPS library provides a whole collection of interfaces needed to
1269  support the internal needs of the CUPS software as well as the needs of
1270  applications, filters, printer drivers, and backends.</P>
1271 <P>Unlike the rest of CUPS, the CUPS API library is provided under the
1272  GNU Library General Public License. This means that you can use the
1273  CUPS API library in both proprietary and open-source programs.</P>
1274 <P>Programs that use the CUPS API library typically will include the <CODE>
1275 &lt;cups/cups.h&gt;</CODE> header file:</P>
1276 <UL>
1277 <PRE>
1278 #include &lt;cups/cups.h&gt;
1279
1280 ...
1281
1282 jobid = cupsPrintFile(&quot;myprinter&quot;, &quot;filename.ps&quot;, &quot;title&quot;,
1283                       num_options, options);
1284 </PRE>
1285 </UL>
1286 <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS
1287  API library:</P>
1288 <UL>
1289 <PRE>
1290 <B>cc -o program program.c -lcups ENTER</B>
1291 </PRE>
1292 </UL>
1293 <P>Additional options and libraries may be required depending on the
1294  operating system and the location of the CUPS API library.</P>
1295 <H3><A NAME="3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></H3>
1296 <P>GNU autoconf is a popular configuration tool used by many programs.
1297  Add the following lines to your<VAR> configure.in file to check for the
1298  CUPS API library in your configuration script:</VAR></P>
1299 <UL>
1300 <PRE>
1301 AC_CHECK_LIB(socket,socket,
1302 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1303         LIBS=&quot;-lsocket $LIBS&quot;
1304 else
1305         echo &quot;Not using -lsocket since you are running IRIX.&quot;
1306 fi)
1307 AC_CHECK_LIB(nsl,gethostbyaddr,
1308 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1309         LIBS=&quot;-lnsl $LIBS&quot;
1310 else
1311         echo &quot;Not using -lnsl since you are running IRIX.&quot;
1312 fi)
1313
1314 AC_CHECK_LIB(cups,httpConnect)
1315 </PRE>
1316 </UL>
1317 <H2><A NAME="3_2">Printing Services</A></H2>
1318 <P>The CUPS API library provides some basic printing services for
1319  applications that need to print files.</P>
1320 <H3><A NAME="3_2_1">Include Files</A></H3>
1321 <P>The include file used by all of these functions is <CODE>
1322 &lt;cups/cups.h&gt;</CODE>:</P>
1323 <UL>
1324 <PRE>
1325 #include &lt;cups/cups.h&gt;
1326 </PRE>
1327 </UL>
1328 <H3><A NAME="3_2_2">Printing a File</A></H3>
1329 <P>The CUPS API provides two functions for printing files. The first is <CODE>
1330 cupsPrintFile</CODE> which prints a single named file:</P>
1331 <UL>
1332 <PRE>
1333 #include &lt;cups/cups.h&gt;
1334
1335 ...
1336
1337 int jobid;
1338
1339 ...
1340
1341 jobid = cupsPrintFile(&quot;<I>name</I>&quot;, &quot;<I>filename</I>&quot;, &quot;<I>title</I>&quot;, 0, NULL);
1342 </PRE>
1343 </UL>
1344 <P>The <CODE>name</CODE> string is the name of the printer or class to
1345  print to. The <CODE>filename</CODE> string is the name of the file to
1346  print. The <CODE>title</CODE> string is the name of the print job, e.g.
1347  &quot;Acme Word Document&quot;.</P>
1348 <P>The return value is a unique ID number for the print job or 0 if
1349  there was an error.</P>
1350 <H3><A NAME="3_2_3">Printing Multiple Files</A></H3>
1351 <P>The second printing function is <CODE>cupsPrintFiles</CODE>:</P>
1352 <UL>
1353 <PRE>
1354 #include &lt;cups/cups.h&gt;
1355
1356 ...
1357
1358 int        jobid;
1359 int        num_files;
1360 const char *files[100];
1361 ...
1362
1363 jobid = cupsPrintFiles(&quot;name&quot;, <I>num_files</I>, <I>files</I>, &quot;title&quot;, 0, NULL);
1364 </PRE>
1365 </UL>
1366 <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
1367 , you pass a file count (<CODE>num_files</CODE>) and filename pointer
1368  array (<CODE>files</CODE>) for each file that you want to print.</P>
1369 <P>As with <CODE>cupsPrintFile()</CODE>, the return value is a unique ID
1370  for the print job.</P>
1371 <H3><A NAME="3_2_4">Cancelling Jobs</A></H3>
1372 <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:</P>
1373 <UL>
1374 <PRE>
1375 #include &lt;cups/cups.h&gt;
1376
1377 ...
1378
1379 int jobid;
1380 int status;
1381 ...
1382
1383 status = cupsCancelJob(&quot;<I>name</I>&quot;, <I>jobid</I>);
1384 </PRE>
1385 </UL>
1386 <P>The <CODE>name</CODE> string specifies the destination and is used to
1387  determine the server to send the request to. The <CODE>jobid</CODE>
1388  value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
1389  or <CODE>cupsPrintFiles()</CODE> call.</P>
1390 <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
1391  successfully cancelled and <CODE>0</CODE> if there was an error.</P>
1392 <H3><A NAME="3_2_5">Getting the Available Printers and Classes</A></H3>
1393 <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list of
1394  the available printers, classes, and instances that a user has defined:</P>
1395 <UL>
1396 <PRE>
1397 #include &lt;cups/cups.h&gt;
1398
1399 ...
1400
1401 int         num_dests;
1402 cups_dest_t *dests;
1403
1404 ...
1405
1406 num_dests = cupsGetDests(&amp;dests);
1407 </PRE>
1408 </UL>
1409 <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure
1410  which defines the printer or class name, the instance name (if any), if
1411  it is the default destination, and the default options the user has
1412  defined for the destination:</P>
1413 <UL>
1414 <PRE>
1415 typedef struct               /**** Destination ****/
1416 {
1417   char          *name,       /* Printer or class name */
1418                 *instance;   /* Local instance name or NULL */
1419   int           is_default;  /* Is this printer the default? */
1420   int           num_options; /* Number of options */
1421   cups_option_t *options;    /* Options */
1422 } cups_dest_t;
1423 </PRE>
1424 </UL>
1425 <P>The destinations are sorted by name and instance for your
1426  convenience. Once you have the list of available destinations, you can
1427  lookup a specific destination using the <CODE>cupsGetDest()</CODE>
1428  function:</P>
1429 <UL>
1430 <PRE>
1431 #include &lt;cups/cups.h&gt;
1432
1433 ...
1434
1435 int         num_dests;
1436 cups_dest_t *dests;
1437 cups_dest_t *mydest;
1438
1439 ...
1440
1441 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1442 </PRE>
1443 </UL>
1444 <P>The <CODE>name</CODE> string is the printer or class name. You can
1445  pass a value of <CODE>NULL</CODE> to get the default destination.</P>
1446 <P>The <CODE>instance</CODE> string is the user-defined instance name.
1447  Pass <CODE>NULL</CODE> to select the default instance, e.g. &quot;name&quot;
1448  instead of &quot;name/instance&quot;.</P>
1449 <H3><A NAME="3_2_6">Printing with Options</A></H3>
1450 <P>All of the previous printing examples have passed <CODE>0</CODE> and <CODE>
1451 NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
1452  and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments
1453  are the number of options and a pointer to the option array:</P>
1454 <UL>
1455 <PRE>
1456 int cupsPrintFile(const char *name, const char *filename, const char *title,
1457                   int num_options, cups_option_t *options);
1458 int cupsPrintFiles(const char *name, int num_files, const char **files,
1459                    const char *title, int num_options,
1460                    cups_option_t *options);
1461 </PRE>
1462 </UL>
1463 <P>The <CODE>cups_option_t</CODE> structure holds each option and its
1464  value. These are converted as needed and passed to the CUPS server when
1465  printing a file.</P>
1466 <P>The simplest way of handling options is to use the <CODE>num_options</CODE>
1467  and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
1468  structure described earlier:</P>
1469 <UL>
1470 <PRE>
1471 #include &lt;cups/cups.h&gt;
1472
1473 ...
1474
1475 int         jobid;
1476 int         num_dests;
1477 cups_dest_t *dests;
1478 cups_dest_t *mydest;
1479
1480 ...
1481
1482 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1483
1484 jobid  = cupsPrintFile(mydest-&gt;name, &quot;filename&quot;, &quot;title&quot;,
1485                        mydest-&gt;num_options, mydest-&gt;options);
1486 </PRE>
1487 </UL>
1488 <P>This effectively uses the options a user has previous selected
1489  without a lot of code.</P>
1490 <H3><A NAME="3_2_7">Setting Printer Options</A></H3>
1491 <P>Options can also be set by your program using the <CODE>
1492 cupsAddOption()</CODE> function:</P>
1493 <UL>
1494 <PRE>
1495 #include &lt;cups/cups.h&gt;
1496
1497 ...
1498
1499 int           num_options;
1500 cups_option_t *options;
1501
1502 ...
1503
1504 num_options = 0;
1505 options     = NULL;
1506
1507 ...
1508
1509 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
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 </PRE>
1514 </UL>
1515 <P>The <CODE>name</CODE> string is the name of the option, and the <CODE>
1516 value</CODE> string is the value for that option.</P>
1517 <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
1518  options. Since adding two options with the same name overwrites the
1519  first value with the second, do not assume that calling <CODE>
1520 cupsAddOptions()</CODE> 20 times will result in 20 options.</P>
1521 <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the
1522  options:</P>
1523 <UL>
1524 <PRE>
1525 #include &lt;cups/cups.h&gt;
1526
1527 ...
1528
1529 int           num_options;
1530 cups_option_t *options;
1531
1532 ...
1533
1534 cupsFreeOptions(num_options, options);
1535 </PRE>
1536 </UL>
1537 <H3><A NAME="3_2_8">Getting Errors</A></H3>
1538 <P>If any of the CUPS API printing functions returns an error, the
1539  reason for that error can be found by calling <CODE>cupsLastError()</CODE>
1540  and <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE>
1541  returns the last IPP error code that was encountered. <CODE>
1542 cupsErrorString()</CODE> converts the error code to a localized message
1543  string suitable for presentation to the user:</P>
1544 <UL>
1545 <PRE>
1546 #include &lt;cups/cups.h&gt;
1547
1548 ...
1549
1550 int jobid;
1551
1552 ...
1553
1554 if (jobid == 0)
1555   puts(cupsErrorString(cupsLastError()));
1556 </PRE>
1557 </UL>
1558 <H3><A NAME="3_2_9">Passwords and Authentication</A></H3>
1559 <P>CUPS supports authentication of any request, including submission of
1560  print jobs. The default mechanism for getting the username and password
1561  is to use the login user and a password from the console.</P>
1562 <P>To support other types of applications, in particular Graphical User
1563  Interfaces (&quot;GUIs&quot;), the CUPS API provides functions to set the default
1564  username and to register a callback function that returns a password
1565  string.</P>
1566 <P>The<A HREF="cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>
1567  function is used to set a password callback in your program. Only one
1568  function can be used at any time.</P>
1569 <P>The<A HREF="cupsSetUser"> <CODE>cupsSetUser()</CODE></A> function
1570  sets the current username for authentication. This function can be
1571  called by your password callback function to change the current
1572  username as needed.</P>
1573 <P>The following example shows a simple password callback that gets a
1574  username and password from the user:</P>
1575 <UL>
1576 <PRE>
1577 #include &lt;cups/cups.h&gt;
1578
1579 const char *
1580 my_password_cb(const char *prompt)
1581 {
1582   char  user[65];
1583
1584
1585   puts(prompt);
1586
1587  /* Get a username from the user */
1588   printf(&quot;Username: &quot;);
1589   if (fgets(user, sizeof(user), stdin) == NULL)
1590     return (NULL);
1591
1592  /* Strip the newline from the string and set the user */
1593   user[strlen(user) - 1] = '\0';
1594
1595   cupsSetUser(user);
1596
1597  /* Use getpass() to ask for the password... */
1598   return (getpass(&quot;Password: &quot;));
1599 }
1600
1601 ...
1602
1603 cupsSetPasswordCB(my_password_cb);
1604 </PRE>
1605 </UL>
1606 <P>Similarly, a GUI interface could display the prompt string in a
1607  window with input fields for the username and password. The username
1608  should probably default to the value of<A HREF="#cupsUser"> <CODE>
1609 cupsUser()</CODE></A> to make things easier on the user.</P>
1610 <H2><A NAME="3_3">PPD Services</A></H2>
1611 <P>CUPS includes functions to access and manipulate PostScript Printer
1612  Description (&quot;PPD&quot;) files that are used with the printer drivers in
1613  CUPS.</P>
1614 <P>Each PPD file enumerates the available features provided by a
1615  printer, including conflict information for specific options (e.g.
1616  can't duplex output on envelopes.)</P>
1617 <H3><A NAME="3_3_1">Include Files</A></H3>
1618 <P>Include the <CODE>&lt;cups/ppd.h&gt;</CODE> header file to use the PPD
1619  functions:</P>
1620 <UL>
1621 <PRE>
1622 #include &lt;cups/ppd.h&gt;
1623 </PRE>
1624 </UL>
1625 <P>This header file is also included by the <CODE>&lt;cups/cups.h&gt;</CODE>
1626  header file.</P>
1627 <H3><A NAME="3_3_2">Getting a PPD File for a Printer</A></H3>
1628 <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
1629  named printer or class:</P>
1630 <UL>
1631 <PRE>
1632 #include &lt;cups/cups.h&gt;
1633
1634 ...
1635
1636 const char *filename;
1637
1638 filename = cupsGetPPD(&quot;<I>name</I>&quot;);
1639 </PRE>
1640 </UL>
1641 <P>The <CODE>name</CODE> string is the name of the printer or class,
1642  including the remote server name as appropriate (e.g.
1643  &quot;printer@server&quot;.)</P>
1644 <P>The return value is a pointer to a filename in static storage; this
1645  value is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If
1646  the printer or class does not exist, a <CODE>NULL</CODE> pointer will
1647  be returned.</P>
1648 <H3><A NAME="3_3_3">Loading a PPD File</A></H3>
1649 <P>The <CODE>ppdOpenFile()</CODE> function &quot;opens&quot; a PPD file and loads
1650  it into memory:</P>
1651 <UL>
1652 <PRE>
1653 #include &lt;cups/ppd.h&gt;
1654
1655 ...
1656
1657 ppd_file_t *ppd;
1658
1659 ppd = ppdOpenFile(&quot;<I>filename</I>&quot;);
1660 </PRE>
1661 </UL>
1662 <P>The <CODE>filename</CODE> string is the name of the file to load,
1663  such as the value returned by the <CODE>cupsGetPPD()</CODE> function.</P>
1664 <P>The return value is a pointer to a structure describing the contents
1665  of the PPD file or NULL if the PPD file could not be read.</P>
1666 <H3><A NAME="3_3_4">Freeing PPD File Information</A></H3>
1667 <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE>
1668  function to free all memory that has been used:</P>
1669 <UL>
1670 <PRE>
1671 #include &lt;cups/ppd.h&gt;
1672
1673 ...
1674
1675 ppd_file_t *ppd;
1676
1677 ...
1678
1679 ppdClose(ppd);
1680 </PRE>
1681 </UL>
1682 <H3><A NAME="3_3_5">The PPD File Structure</A></H3>
1683 <P>Each PPD file contains a number of capability attributes, printer
1684  options, and conflict definitions. The page size options also include
1685  the physical margins for the printer and the minimum and maximum sizes
1686  for the printer. All of this information is stored in the <CODE>
1687 ppd_file_t</CODE> structure.</P>
1688 <H4>Capabilities</H4>
1689 <P>Each PPD file contains a number of informational attributes that
1690  describe the capabilities of the printer. These are provided in the <CODE>
1691 ppd_file_t</CODE> structure in the following members:
1692 <CENTER>
1693 <TABLE BORDER="1" WIDTH="80%">
1694 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
1695 <TR><TD><CODE>accurate_screens</CODE></TD><TD><CODE>int</CODE></TD><TD>1
1696  = supports accurate screens</TD></TR>
1697 <TR><TD><CODE>color_device</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1698  color device</TD></TR>
1699 <TR><TD><CODE>colorspace</CODE></TD><TD><CODE>ppd_cs_t</CODE></TD><TD>
1700 Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB,
1701  PPD_CS_RGBK, PPD_CS_N</TD></TR>
1702 <TR><TD><CODE>contone_only</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1703  printer is continuous tone only</TD></TR>
1704 <TR><TD><CODE>num_emulations
1705 <BR> emulations</CODE></TD><TD><CODE>int
1706 <BR> ppd_emul_t *</CODE></TD><TD>Emulations supported by the printer</TD>
1707 </TR>
1708 <TR><TD><CODE>flip_duplex</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1709  need to flip odd pages when duplexing</TD></TR>
1710 <TR><TD><CODE>num_fonts
1711 <BR> fonts</CODE></TD><TD><CODE>int
1712 <BR> char **</CODE></TD><TD>The fonts available on the printer.</TD></TR>
1713 <TR><TD><CODE>jcl_begin
1714 <BR> jcl_ps
1715 <BR> jcl_end</CODE></TD><TD><CODE>char *</CODE></TD><TD>Job Control
1716  Language commands for PostScript output</TD></TR>
1717 <TR><TD><CODE>landscape</CODE></TD><TD><CODE>int</CODE></TD><TD>
1718 Landscape orientation, -90 or 90 degrees</TD></TR>
1719 <TR><TD><CODE>lang_encoding</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1720 The character used for the option strings</TD></TR>
1721 <TR><TD><CODE>lang_version</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1722 The language used for the options strings (English, French, etc.)</TD></TR>
1723 <TR><TD><CODE>language_level</CODE></TD><TD><CODE>int</CODE></TD><TD>
1724 PostScript language level, 1 to 3</TD></TR>
1725 <TR><TD><CODE>manual_copies</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1726  Copies are done manually</TD></TR>
1727 <TR><TD><CODE>model_number</CODE></TD><TD><CODE>int</CODE></TD><TD>
1728 Driver-specific model number.</TD></TR>
1729 <TR><TD><CODE>patches</CODE></TD><TD><CODE>char *</CODE></TD><TD>Patch
1730  commands to send to the printer</TD></TR>
1731 <TR><TD><CODE>manufacturer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1732 The Manufacturer attribute from the PPD file, if any</TD></TR>
1733 <TR><TD><CODE>modelname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1734  ModelName attribute from the PPD file</TD></TR>
1735 <TR><TD><CODE>nickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1736  NickName attribute from the PPD file, if any</TD></TR>
1737 <TR><TD><CODE>product</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1738  Product attribute from the PPD file, if any</TD></TR>
1739 <TR><TD><CODE>shortnickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1740 The ShortNickName attribute from the PPD file, if any</TD></TR>
1741 <TR><TD><CODE>throughput</CODE></TD><TD><CODE>int</CODE></TD><TD>Number
1742  of pages per minute</TD></TR>
1743 <TR><TD><CODE>ttrasterizer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1744 The TruType font rasterizer (Type42)</TD></TR>
1745 <TR><TD><CODE>variable_sizes</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1746  supports variable sizes</TD></TR>
1747 </TABLE>
1748 </CENTER>
1749 </P>
1750 <H4>Options and Groups</H4>
1751 <P>PPD files support multiple options, which are stored in <CODE>
1752 ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by the PPD
1753  functions.</P>
1754 <P>Each option in turn is associated with a group stored in the <CODE>
1755 ppd_group_t</CODE> structure. Groups can be specified in the PPD file;
1756  if an option is not associated with a group then it is put in a
1757  &quot;General&quot; or &quot;Extra&quot; group depending on the option.</P>
1758 <P>Groups can also have sub-groups; CUPS currently limits the depth of
1759  sub-groups to 1 level to reduce programming complexity.</P>
1760 <H4>Conflicts</H4>
1761 <P>PPD files support specification of conflict conditions between
1762  different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
1763  structures which specify the options that conflict with each other.</P>
1764 <H4>Page Sizes</H4>
1765 <P>PPD files specify all of the available pages sizes and the physical
1766  margins associated with them. These sizes are stored in <CODE>
1767 ppd_size_t</CODE> structures and are available in the <CODE>num_sizes</CODE>
1768  and <CODE>sizes</CODE> members of the <CODE>ppd_file_t</CODE>
1769  structure. You can lookup a particular page size with the <CODE>
1770 ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and <CODE>
1771 ppdPageSize()</CODE> functions:</P>
1772 <UL>
1773 <PRE>
1774 #include &lt;cups/ppd.h&gt;
1775
1776 ...
1777
1778 ppd_file_t *ppd;
1779 ppd_size_t *size;
1780 float      width;
1781 float      length;
1782
1783 ...
1784
1785 size   = ppdPageSize(ppd, &quot;<I>size</I>&quot;);
1786 width  = ppdPageWidth(ppd, &quot;<I>size</I>&quot;);
1787 length = ppdPageLength(ppd, &quot;<I>size</I>&quot;);
1788 </PRE>
1789 </UL>
1790 <P>The <CODE>size</CODE> string is the named page size option. The width
1791  and length are in points; there are 72 points per inch. The <CODE>
1792 ppd_size_t</CODE> structure contains the width, length, and margin
1793  information:</P>
1794 <UL>
1795 <PRE>
1796 typedef struct    /**** Page Sizes ****/
1797 {
1798   int   marked;   /* Page size selected? */
1799   char  name[41]; /* Media size option */
1800   float width,    /* Width of media in points */
1801         length,   /* Length of media in points */
1802         left,     /* Left printable margin in points */
1803         bottom,   /* Bottom printable margin in points */
1804         right,    /* Right printable margin in points */
1805         top;      /* Top printable margin in points */
1806 } ppd_size_t;
1807 </PRE>
1808 </UL>
1809 <H4>Custom Page Sizes</H4>
1810 <P>Besides the standard page sizes listed in a PPD file, some printers
1811  support variable or custom page sizes. If <CODE>variables_sizes</CODE>
1812  is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and <CODE>
1813 custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> structure
1814  define the limits of the variable sizes.</P>
1815 <P>To get the resulting media size, use a page size string of <CODE>
1816 Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE> and <CODE>
1817 length</CODE> are integer values in points:</P>
1818 <UL>
1819 <PRE>
1820 Custom.612x792   [8.5 inches wide, 11 inches long]
1821 Custom.1224x792  [17 inches wide, 11 inches long]
1822 </PRE>
1823 </UL>
1824 <H3><A NAME="3_3_6">Marking Options</A></H3>
1825 <P>Before marking any user-defined options, call the <CODE>
1826 ppdMarkDefaults()</CODE> function to mark the default options from the
1827  PPD file:</P>
1828 <UL>
1829 <PRE>
1830 #include &lt;cups/ppd.h&gt;
1831
1832 ...
1833
1834 ppd_file_t *ppd;
1835
1836 ...
1837
1838 ppdMarkDefaults(ppd);
1839 </PRE>
1840 </UL>
1841 <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark
1842  individual options:</P>
1843 <UL>
1844 <PRE>
1845 #include &lt;cups/ppd.h&gt;
1846
1847 ...
1848
1849 ppd_file_t *ppd;
1850 int        conflicts;
1851
1852 ...
1853
1854 conflicts = ppdMarkOption(ppd, &quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;);
1855 </PRE>
1856 </UL>
1857 <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
1858  particular option and choice, respectively. The return value is 0 if
1859  there are not conflicts created by the selection.</P>
1860 <P>CUPS also provides a convenience function for marking all options in
1861  the <CODE>cups_option_t</CODE> structure:</P>
1862 <UL>
1863 <PRE>
1864 #include &lt;cups/cups.h&gt;
1865
1866 ...
1867
1868 ppd_file_t    *ppd;
1869 int           num_options;
1870 cups_option_t *options;
1871 int           conflicts;
1872
1873 ...
1874
1875 conflicts = cupsMarkOptions(ppd, num_options, options);
1876 </PRE>
1877 </UL>
1878 <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
1879  IPP job template attributes to PPD options. The return value is the
1880  number of conflicts present.</P>
1881 <H3><A NAME="3_3_7">Checking for Conflicts</A></H3>
1882 <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
1883  functions return the number of conflicts with the currently marked
1884  options.</P>
1885 <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
1886  conflicts after you have marked all of the options:</P>
1887 <UL>
1888 <PRE>
1889 #include &lt;cups/cups.h&gt;
1890
1891 ...
1892
1893 ppd_file_t *ppd;
1894 int        conflicts;
1895
1896 ...
1897
1898 conflicts = ppdConflicts(ppd);
1899 </PRE>
1900 </UL>
1901 <P>The return value is the number of conflicting options, or 0 if there
1902  are no conflicts.</P>
1903 <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
1904 <P>This chapter describes how to write a file filter for CUPS.</P>
1905 <H2><A NAME="4_1">Overview</A></H2>
1906 <P>File filters are programs that convert from one or more MIME types to
1907  another type. Filters use a common command-line and environment
1908  interface that allows them to be joined as needed to print files to any
1909  type of printer.</P>
1910 <H3><A NAME="4_1_1">Security Considerations</A></H3>
1911 <P>Filters are normally run as a non-priviledged user, so the major
1912  security consideration is resource utilization - filters should not
1913  depend on unlimited amounts of memory and disk space.</P>
1914 <H3><A NAME="4_1_2">Users and Groups</A></H3>
1915 <P>The default CUPS configuration runs filters as user &quot;lp&quot; and group
1916  &quot;other&quot;.</P>
1917 <H3><A NAME="4_1_3">Temporary Files</A></H3>
1918 <P>Temporary files should be created in the directory specified by the
1919  &quot;TMPDIR&quot; environment variable. The<A HREF="#cupsTempFile"> <CODE>
1920 cupsTempFile()</CODE></A> function can be used to safely choose
1921  temporary files in this directory.</P>
1922 <H3><A NAME="4_1_4">Sending Messages to the User</A></H3>
1923 <P>The CUPS scheduler collects messages sent to the standard error file
1924  by the filter. These messages are relayed to the user based upon the
1925  scheduler <CODE>LogLevel</CODE> directive.</P>
1926 <P>The type of message is determined by an initial prefix sent on each
1927  line:</P>
1928 <UL>
1929 <LI><CODE>DEBUG:</CODE> - a debug message</LI>
1930 <LI><CODE>INFO:</CODE> - an informational message</LI>
1931 <LI><CODE>WARNING:</CODE> - a warning message</LI>
1932 <LI><CODE>ERROR:</CODE> - an error message</LI>
1933 <LI><CODE>PAGE:</CODE> - a page accounting message</LI>
1934 </UL>
1935 <P>If the line of text does not begin with any of the above prefixes, it
1936  is treated as a debug message. Text following the prefix is copied to
1937  the <CODE>printer-state-message</CODE> attribute for the printer, and
1938  also added to the<VAR> error_log</VAR> unless it is an informational or
1939  page accounting message.</P>
1940 <H3><A NAME="4_1_5">Page Accounting</A></H3>
1941 <P>Page accounting messages are used to inform the server when one or
1942  more pages are printed. Each line has the form:</P>
1943 <UL>
1944 <PRE>
1945 PAGE: page-number copy-count
1946 </PRE>
1947 </UL>
1948 <P>The<I> page-number</I> field is the current page number, starting at
1949  1. The<I> copy-count</I> field specifies the number of copies of that
1950  page that was produced.</P>
1951 <P>Page account messages are added to the<VAR> page_log</VAR> file and
1952  cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
1953  the job.</P>
1954 <H3><A NAME="4_1_6">Command-Line Arguments</A></H3>
1955 <P>Every filter accepts exactly 6 or 7 command-line arguments:</P>
1956 <UL>
1957 <PRE>
1958 printer job user title copies options [filename]
1959 </PRE>
1960 <LI><CODE>printer</CODE> - The name of the printer queue (normally this
1961  is the name of the program being run)</LI>
1962 <LI><CODE>job</CODE> - The numeric job ID for the job being printed</LI>
1963 <LI><CODE>user</CODE> - The string from the <CODE>originating-user-name</CODE>
1964  attribute</LI>
1965 <LI><CODE>title</CODE> - The string from the <CODE>job-name</CODE>
1966  attribute</LI>
1967 <LI><CODE>copies</CODE> - The numeric value from the <CODE>number-copies</CODE>
1968  attribute</LI>
1969 <LI><CODE>options</CODE> - String representations of the job template
1970  attributes, separated by spaces. Boolean attributes are provided as
1971  &quot;name&quot; for true values and &quot;noname&quot; for false values. All other
1972  attributes are provided as &quot;name=value&quot; for single-valued attributes
1973  and &quot;name=value1,value2,...,valueN&quot; for set attributes</LI>
1974 <LI><CODE>filename</CODE> - The request file</LI>
1975 </UL>
1976 <P>The<I> filename</I> argument is only provided to the first filter in
1977  the chain; all filters<B> must</B> be prepared to read the print file
1978  from the standard input if the<I> filename</I> argument is omitted.</P>
1979 <H3><A NAME="4_1_7">Copy Generation</A></H3>
1980 <P>The<I> copies</I> argument specifies the number of copies to produce
1981  of the input file. In general, you should only generate copies if the<I>
1982  filename</I> argument is supplied. The only exception to this are
1983  filters that produce device-independent PostScript output (without any
1984  printer commands from the printer's PPD file), since the PostScript
1985  filter <CODE>pstops</CODE> is responsible for copy generation.</P>
1986 <H3><A NAME="4_1_8">Environment Variables</A></H3>
1987 <P>Every filter receives a fixed set of environment variables that can
1988  be used by the filter:</P>
1989 <UL>
1990 <LI><CODE>CHARSET</CODE> - The character set used by the client for this
1991  print file</LI>
1992 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
1993  &quot;application/postscript&quot;</LI>
1994 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files</LI>
1995 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
1996  files</LI>
1997 <LI><CODE>DEVICE_URI</CODE> - The output device URI</LI>
1998 <LI><CODE>LANG</CODE> - The language used by the client for this print
1999  file</LI>
2000 <LI><CODE>PATH</CODE> - The execution path exported to the filter</LI>
2001 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file</LI>
2002 <LI><CODE>PRINTER</CODE> - The name of the printer queue</LI>
2003 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
2004  should use</LI>
2005 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
2006  &quot;CUPS/1.1&quot;</LI>
2007 <LI><CODE>TZ</CODE> - The local timezone</LI>
2008 <LI><CODE>USER</CODE> - The name of the current user</LI>
2009 </UL>
2010 <H2><A NAME="4_2">Dissecting the HP-GL/2 Filter</A></H2>
2011 <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
2012  complex program that converts HP-GL/2 files into device-independent
2013  PostScript output. Since it produces device-independent PostScript
2014  output, it does not need to handle copy generation or writing printer
2015  options from the printer's PPD file.</P>
2016 <H3><A NAME="4_2_1">Initializing the Filter</A></H3>
2017 <P>The first task of any filter is to ensure that the correct number of
2018  command-line arguments are present:</P>
2019 <UL>
2020 <PRE>
2021 if (argc &lt; 6 || argc &gt; 7)
2022 {
2023   fputs(&quot;ERROR: hpgltops job-id user title copies options [file]\n&quot;, stderr);
2024   return (1);
2025 }
2026 </PRE>
2027 </UL>
2028 <P>After this you open the print file or read from the standard input as
2029  needed:</P>
2030 <UL>
2031 <PRE>
2032 FILE *fp;
2033
2034 /*
2035  * If we have 7 arguments, print the file named on the command-line.
2036  * Otherwise, send stdin instead...
2037  */
2038
2039 if (argc == 6)
2040   fp = stdin;
2041 else
2042 {
2043  /*
2044   * Try to open the print file...
2045   */
2046
2047   if ((fp = fopen(argv[6], &quot;rb&quot;)) == NULL)
2048   {
2049     perror(&quot;ERROR: unable to open print file - &quot;);
2050     return (1);
2051   }
2052 }
2053 </PRE>
2054 </UL>
2055 <P>Once the print file has been opened, options can be processed using
2056  the<A HREF="#cupsParseOptions"> <CODE>cupsParseOptions()</CODE></A> and<A
2057 HREF="#cupsGetOption"> <CODE>cupsGetOption()</CODE></A> functions:</P>
2058 <UL>
2059 <PRE>
2060 int           num_options;
2061 cups_option_t *options;
2062 const char    *val;
2063
2064 /*
2065  * Process command-line options and write the prolog...
2066  */
2067
2068 options     = NULL;
2069 num_options = cupsParseOptions(argv[5], 0,
2070
2071 if ((val = cupsGetOption(&quot;blackplot&quot;, num_options, options)) != NULL)
2072   shading = 0;
2073
2074 if ((val = cupsGetOption(&quot;fitplot&quot;, num_options, options)) != NULL)
2075   FitPlot = 1;
2076
2077 if ((val = cupsGetOption(&quot;penwidth&quot;, num_options, options)) != NULL)
2078   PenWidth = (float)atoi(val) * 0.001f;
2079 </PRE>
2080 </UL>
2081 <P>After the options have been processed, the filter writes PostScript
2082  code to the standard output based on the print file, closes the print
2083  file (as needed), and returns 0 to the scheduler.</P>
2084 <H2><A NAME="4_3">PostScript Output</A></H2>
2085 <P>Filters that produce PostScript output must generate output
2086  conforming to the Adobe Document Structuring Conventions, 3.0. In
2087  general this means the beginning of each file must begin with:</P>
2088 <UL>
2089 <PRE>
2090 %!PS-Adobe-3.0
2091 %%BoundingBox: left bottom right top
2092 %%Pages: (atend)
2093 %%EndComments
2094 </PRE>
2095 </UL>
2096 <P>The<I> left</I>,<I> bottom</I>,<I> right</I>, and<I> top</I> values
2097  are integers in points from the lower-lefthand corner of the page.</P>
2098 <P>Pages must be surrounded by:</P>
2099 <UL>
2100 <PRE>
2101 %%Page: number number
2102 gsave
2103 ...
2104 grestore
2105 showpage
2106 </PRE>
2107 </UL>
2108 <P>And the end of each file must contain:</P>
2109 <UL>
2110 <PRE>
2111 %%Trailer
2112 %%Pages: number-pages
2113 %%EOF
2114 </PRE>
2115 </UL>
2116 <P>These comments allow the PostScript filter to correctly perform page
2117  accounting, copy generation, N-up printing, and so forth.</P>
2118 <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A>
2119 </H1>
2120 <P>This chapter discusses how to write a printer driver, which is a
2121  special filter program that converts CUPS raster data into the
2122  appropriate commands and data required for a printer.</P>
2123 <H2><A NAME="5_1">Overview</A></H2>
2124 <P>Raster printers utilitize PPD files that specify one or more
2125  device-specific filters that handle converting print files for the
2126  printer. The simplest raster printer drivers provide a single filter
2127  that converts CUPS raster data to the printer's native format.</P>
2128 <H3><A NAME="5_1_1">CUPS Raster Data</A></H3>
2129 <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists
2130  of a stream of raster page descriptions produced by one of the RIP
2131  filters, such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.</P>
2132 <P>Each page of data begins with a page dictionary structure called<A HREF="#cups_raster_header_t">
2133  <CODE>cups_raster_header_t</CODE></A>. This structure contains the
2134  colorspace, bits per color, media size, media type, hardware
2135  resolution, and so forth.</P>
2136 <P>After the page dictionary comes the page data which is a
2137  full-resolution, uncompressed bitmap representing the page in the
2138  printer's output colorspace.</P>
2139 <H3><A NAME="5_1_2">Page Accounting</A></H3>
2140 <P>Printer drivers must handle all page accounting. This means they must
2141  send &quot;PAGE:&quot; messages to the standard error file for each page (and in
2142  many cases, copy) sent to the printer.</P>
2143 <H3><A NAME="5_1_3">Color Management</A></H3>
2144 <P>Printer drivers can implement their color management via the <CODE>
2145 cupsColorProfile</CODE> attributes in the PPD file or internally in the
2146  driver from a device-independent colorspace. In general, color
2147  management performed by the RIP filters is more efficient than that
2148  performed inside printer drivers.</P>
2149 <P>For example, the <CODE>pstoraster</CODE> filter often only has to
2150  perform a color conversion once each time the color is used for
2151  multiple output pixels, while the raster filter must convert every
2152  pixel on the page.</P>
2153 <H3><A NAME="5_1_4">Device and Bitmap Variables</A></H3>
2154 <P>Besides the standard PostScript page device dictionary variables
2155  defined in the Adobe PostScript Level 3 reference manual, the CUPS
2156  filters support additional variables that are passed in the page device
2157  dictionary header for the page and in some cases control the type of
2158  raster data that is generated:
2159 <CENTER>
2160 <TABLE BORDER="1" WIDTH="90%">
2161 <TR><TH>Variable</TH><TH>Type</TH><TH>Description</TH></TR>
2162 <TR><TD>cupsWidth</TD><TD>read-only integer</TD><TD>Width of bitmap in
2163  pixels</TD></TR>
2164 <TR><TD>cupsHeight</TD><TD>read-only integer</TD><TD>Height of bitmap in
2165  pixels</TD></TR>
2166 <TR><TD>cupsMediaType</TD><TD>read-write integer</TD><TD>Device-specific
2167  media type code</TD></TR>
2168 <TR><TD>cupsBitsPerColor</TD><TD>read-write integer</TD><TD>Number of
2169  bits per color; 1, 2, 4, and 8 are currently supported</TD></TR>
2170 <TR><TD>cupsBitsPerPixel</TD><TD>read-only integer</TD><TD>Number of
2171  bits per pixel; 1 to 32</TD></TR>
2172 <TR><TD>cupsBytesPerLine</TD><TD>read-only integer</TD><TD>Number of
2173  bytes per line of raster graphics</TD></TR>
2174 <TR><TD>cupsColorOrder</TD><TD>read-write enum</TD><TD>The order of
2175  color values in the bitmap:
2176 <UL>
2177 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
2178 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
2179 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
2180 </UL>
2181 </TD></TR>
2182 <TR><TD>cupsColorSpace</TD><TD>read-write enum</TD><TD>The colorspace of
2183  the bitmap:
2184 <UL>
2185 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
2186 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
2187 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
2188 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
2189 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
2190 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
2191 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
2192 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
2193 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
2194 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2195  light cyan, light magenta</LI>
2196 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
2197  magenta, metallic cyan, black</LI>
2198 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
2199  magenta, metallic cyan, metallic grey (silver)</LI>
2200 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
2201  pigment)</LI>
2202 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
2203 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
2204 </UL>
2205 </TD></TR>
2206 <TR><TD>cupsCompression</TD><TD>read-write integer</TD><TD>
2207 Device-specific compression type code</TD></TR>
2208 <TR><TD>cupsRowCount</TD><TD>read-write integer</TD><TD>Device-specific
2209  row count value</TD></TR>
2210 <TR><TD>cupsRowFeed</TD><TD>read-write integer</TD><TD>Device-specific
2211  row feed value</TD></TR>
2212 <TR><TD>cupsRowStep</TD><TD>read-write integer</TD><TD>Device-specific
2213  row step value</TD></TR>
2214 </TABLE>
2215 </CENTER>
2216 </P>
2217 <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit
2218  per color are transmitted to the raster driver in KCMY colorspace; the
2219  driver is responsible for producing the correct separation of normal
2220  and light cyan and magenta inks.</P>
2221 <H2><A NAME="5_2">Dissecting the HP-PCL Driver</A></H2>
2222 <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>)
2223  converts bitmap data from the raster filters into HP-PCL commands for
2224  most PCL-compatible printers. The actual format of the raster data is
2225  controlled by the PPD file being used -<VAR> deskjet.ppd</VAR> or<VAR>
2226  laserjet.ppd</VAR>.</P>
2227 <H3><A NAME="5_2_1">PPD Files</A></H3>
2228 <P>PPD files play an important part of all raster printer drivers.
2229  Options defined in the PPD file contain PostScript commands that
2230  control the raster data that is sent to the printer driver.</P>
2231 <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, <CODE>
2232 InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, and <CODE>
2233 Resolution</CODE> options. Each option is shown using the standard PPD
2234  format:</P>
2235 <UL>
2236 <PRE>
2237 *OpenUI *PageSize/Media Size: PickOne
2238 *OrderDependency: 10 AnySetup *PageSize
2239 *DefaultPageSize: Letter
2240 *PageSize Letter/US Letter: &quot;&lt;&lt;
2241 /PageSize [612 792]
2242 /ImagingBBox null
2243 &gt;&gt; setpagedevice&quot;
2244 *End
2245 *PageSize Legal/US Legal: &quot;&lt;&lt;
2246 /PageSize [612 1008]
2247 /ImagingBBox null
2248 &gt;&gt; setpagedevice&quot;
2249 *End
2250 *PageSize A4/A4: &quot;&lt;&lt;
2251 /PageSize [595 842]
2252 /ImagingBBox null
2253 &gt;&gt; setpagedevice&quot;
2254 *End
2255 *CloseUI: *PageSize
2256 </PRE>
2257 </UL>
2258 <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
2259  name is the option with an asterisk (*) in front of it. The first name
2260  is usually followed by a slash (/) and a human-readable version of the
2261  option name.</P>
2262 <P>Every option<B> must</B> have a default value, specified using the <CODE>
2263 Default<I>Option</I></CODE> keyword.</P>
2264 <P>Each option begins with the option name followed by the computer and
2265  human-readable values. The PostScript commands follow these inside
2266  double quotes. PostScript commands can be provided on a single line:</P>
2267 <UL>
2268 <PRE>
2269 *PageSize A4/A4: &quot;&lt;&lt;/PageSize[595 842]/ImagingBBox null&gt;&gt; setpagedevice&quot;
2270 </PRE>
2271 </UL>
2272 <P>or broken down on separate lines using the <CODE>End</CODE> keyword
2273  to terminate them:</P>
2274 <UL>
2275 <PRE>
2276 *PageSize A4/A4: &quot;&lt;&lt;
2277 /PageSize [595 842]
2278 /ImagingBBox null
2279 &gt;&gt; setpagedevice&quot;
2280 *End
2281 </PRE>
2282 </UL>
2283 <P>The choice of the two formats is usually esthetic. However, each line
2284  in a PPD file must not exceed 255 characters, so if your PostScript
2285  commands are long you may need to break them up on separate lines.</P>
2286 <H3><A NAME="5_2_2">Reading Raster Data</A></H3>
2287 <P>As with any filter, your printer driver should handle raster data
2288  from a filename specified on the command-line or from the standard
2289  input. The<A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>
2290  function opens a raster stream for printing:</P>
2291 <UL>
2292 <PRE>
2293 int           fd;   /* File descriptor */
2294 cups_raster_t *ras; /* Raster stream for printing */
2295
2296
2297 /*
2298  * Check for valid arguments...
2299  */
2300
2301 if (argc &lt; 6 || argc &gt; 7)
2302 {
2303  /*
2304   * We don't have the correct number of arguments; write an error message
2305   * and return.
2306   */
2307
2308   fputs(&quot;ERROR: rastertopcl job-id user title copies options [file]\n&quot;, stderr);
2309   return (1);
2310 }
2311
2312 /*
2313  * Open the page stream...
2314  */
2315
2316 if (argc == 7)
2317 {
2318   if ((fd = open(argv[6], O_RDONLY)) == -1)
2319   {
2320     perror(&quot;ERROR: Unable to open raster file - &quot;);
2321     sleep(1);
2322     return (1);
2323   }
2324 }
2325 else
2326   fd = 0;
2327
2328 ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
2329 </PRE>
2330 </UL>
2331 <P>Once you have opened the raster stream you just need to read each
2332  page and print it:</P>
2333 <UL>
2334 <PRE>
2335 cups_raster_header_t header;
2336 int                  y;
2337 unsigned char        data[8192];
2338
2339 while (cupsRasterReadHeader(ras, &amp;header))
2340 {
2341   ... initialize the printer ...
2342   for (y = header.cupsHeight; y &gt; 0; y ++)
2343   {
2344     cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
2345     ... send raster line to printer ...
2346   }
2347 }
2348 </PRE>
2349 </UL>
2350 <P>After you have processed all pages, close the raster stream and
2351  return:</P>
2352 <UL>
2353 <PRE>
2354 cupsRasterClose(ras);
2355
2356 return (0);
2357 </PRE>
2358 </UL>
2359 <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
2360 <P>This chapter describes how to write a backend for CUPS. Backends
2361  communicate directly with printers and allow printer drivers and
2362  filters to send data using any type of connection transparently.</P>
2363 <H2><A NAME="6_1">Overview</A></H2>
2364 <P>Backends are special filters that communicate with printers directly.
2365  They are treated slightly differently than filters, however, and have
2366  some unique requirements.</P>
2367 <H3><A NAME="6_1_1">Security Considerations</A></H3>
2368 <P>Backends are run as the root user, so special care must be taken to
2369  avoid potential security violations. In particular, remember that a
2370  backend will be able to manipulate disk files, devices, and other
2371  resources that potentially could damage a system or printer.</P>
2372 <H3><A NAME="6_1_2">Command-Line Arguments</A></H3>
2373 <P>Besides the standard filter arguments, backends are also run with no
2374  arguments to get a list of available devices. This discovery process is
2375  described later in this chapter.</P>
2376 <H3><A NAME="6_1_3">Copy Generation</A></H3>
2377 <P>Like filters, backends should send multiple copies of the print file
2378  only if a filename is supplied on the command-line. Otherwise the
2379  backend should assume that the upstream filter has already added the
2380  necessary commands or data to produce the multiple copies.</P>
2381 <H3><A NAME="6_1_4">Page Accounting</A></H3>
2382 <P>Backend filters generally do not do page accounting, however they
2383  should at a minimum produce a single page message for each copy that is
2384  produced when a filename is present on the command-line. This is
2385  because the user selected &quot;raw&quot; printing and no other accounting
2386  information is possible.</P>
2387 <H3><A NAME="6_1_5">Exclusive Access</A></H3>
2388 <P>Backends that talk to local character or block devices should open
2389  the device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate
2390  with other printers defined for the same device.</P>
2391 <H3><A NAME="6_1_6">Retries</A></H3>
2392 <P>All backends<B> must</B> retry connections to the device. This
2393  includes backends that talk to local character or block devices, as the
2394  user may define more than one printer queue pointing at the same
2395  physical device.</P>
2396 <P>To prevent excess CPU utilitization, the backend should go to sleep
2397  for an amount of time between retries; the CUPS-supplied backends retry
2398  once every 30 seconds.</P>
2399 <H2><A NAME="6_2">Dissecting the Serial Port Backend</A></H2>
2400 <P>The serial port backend provides support for serial printers. Since
2401  it does everything a good backend needs to do, it provides an excellent
2402  example of what to do.</P>
2403 <H3><A NAME="6_2_1">Supporting Device Discovery</A></H3>
2404 <P>As previously noted, backends are special filter programs that talk
2405  to printer devices. Another task a backend must perform is to list the
2406  available devices it supports. The backend lists the available devices
2407  when no additioanl arguments are supplied on the command-line (i.e.
2408  just the command name...)</P>
2409 <P>The serial backend lists devices by looking at serial port files in
2410  the<VAR> /dev</VAR> directory, by consulting a hardware inventory
2411  (IRIX), and in some cases by trying to open the ports to see if they
2412  actually exist.</P>
2413 <P>Once it finds a serial port it writes a single line for each port to
2414  the standard error file. Each line looks like this:</P>
2415 <UL>
2416 <PRE>
2417 serial serial:/dev/ttyS0?baud=115200 &quot;Unknown&quot; &quot;Serial Port 1&quot;
2418 </PRE>
2419 </UL>
2420 <P>The first word &quot;serial&quot; is the<I> device class</I>; this identifies
2421  the class of device which can be used to categorize it in user
2422  interfaces. CUPS currently recognizes the following classes:</P>
2423 <UL>
2424 <LI>&quot;file&quot; - a disk file.</LI>
2425 <LI>&quot;direct&quot; - a parallel or fixed-rate serial data port, currently used
2426  for Centronics, IEEE-1284, and USB printer ports.</LI>
2427 <LI>&quot;serial&quot; - a variable-rate serial port.</LI>
2428 <LI>&quot;network&quot; - a network connection, typically via AppSocket, HTTP,
2429  IPP, LPD, or SMB/CIFS protocols.</LI>
2430 </UL>
2431 <P>After the device class is the<I> device URI</I>, in this case
2432  &quot;serial:/dev/ttyS0?baud=115200&quot;. This is the URI that should be used by
2433  the user to select this port. For serial ports, the &quot;baud=115200&quot;
2434  specifies the maximum baud rate supported by the port - the actual
2435  value will vary based on the speed the user selects for the printer.</P>
2436 <P>The last two strings are the model and description for the port. The
2437  &quot;Unknown&quot; string means that the printer model is unknown - some devices
2438  are able to provide a make and model such as &quot;HP DeskJet&quot; that allows
2439  users and software to choose an appropriate printer driver more easily.
2440  Both the model and description must be enclosed inside double quotes.</P>
2441 <H3><A NAME="6_2_2">Opening the Serial Port</A></H3>
2442 <P>As noted previously, all backends should open device files in
2443  exclusive mode, and retry as needed until the port is available. The
2444  serial port does this using a <CODE>do-while</CODE> loop:</P>
2445 <UL>
2446 <PRE>
2447 do
2448 {
2449   if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
2450   {
2451     if (errno == EBUSY)
2452     {
2453       fputs(&quot;INFO: Serial port busy; will retry in 30 seconds...\n&quot;, stderr);
2454       sleep(30);
2455     }
2456     else
2457     {
2458       perror(&quot;ERROR: Unable to open serial port device file&quot;);
2459       return (1);
2460     }
2461   }
2462 }
2463 while (fd &lt; 0);
2464 </PRE>
2465 </UL>
2466 <P>If the port is busy or in use by another process, the backend will go
2467  to sleep for 30 seconds and try again. If another error is detected a
2468  message is sent to the user and the backend aborts the print job until
2469  the problem can be corrected.</P>
2470 <H3><A NAME="6_2_3">Writing Data to the Port</A></H3>
2471 <P>Network and character devices pose an interesting problem when
2472  writing data to the port - they may not be able to write all of the
2473  bytes in your buffer before returning. To work around this problem you
2474  must loop until all bytes have been written:</P>
2475 <UL>
2476 <PRE>
2477 while (nbytes &gt; 0)
2478 {
2479   if ((wbytes = write(fd, bufptr, nbytes)) &lt; 0)
2480     if (errno == ENOTTY)
2481       wbytes = write(fd, bufptr, nbytes);
2482
2483   if (wbytes &lt; 0)
2484   {
2485     perror(&quot;ERROR: Unable to send print file to printer&quot;);
2486     break;
2487   }
2488
2489   nbytes -= wbytes;
2490   bufptr += wbytes;
2491 }
2492 </PRE>
2493 </UL>
2494 <P>The check for the <CODE>ENOTTY</CODE> error is needed on some
2495  platforms to clear an error from a previous <CODE>ioctl()</CODE> call.</P>
2496 <H3><A NAME="6_2_4">Finishing Up</A></H3>
2497 <P>Once you have sent the print file, return 0 if the file printed
2498  successfully or 1 if it did not. This will allow the scheduler to stop
2499  the print job if there is a device error, preserving the print job for
2500  later printing once the problem has been corrected.</P>
2501 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
2502 <H2 ALIGN="CENTER"><A NAME="7_1">Common UNIX Printing System License
2503  Agreement</A></H2>
2504 <P ALIGN="CENTER">Copyright 1997-2001 by Easy Software Products
2505 <BR> 44141 AIRPORT VIEW DR STE 204
2506 <BR> HOLLYWOOD, MARYLAND 20636-3111 USA
2507 <BR>
2508 <BR> Voice: +1.301.373.9600
2509 <BR> Email:<A HREF="mailto:cups-info@cups.org"> cups-info@cups.org</A>
2510 <BR> WWW:<A HREF="http://www.cups.org"> http://www.cups.org</A></P>
2511 <H3><A NAME="7_1_1">Introduction</A></H3>
2512 <P>The Common UNIX Printing System<SUP>TM</SUP>, (&quot;CUPS<SUP>TM</SUP>&quot;),
2513  is provided under the GNU General Public License (&quot;GPL&quot;) and GNU
2514  Library General Public License (&quot;LGPL&quot;), Version 2. A copy of these
2515  licenses follow this introduction.</P>
2516 <P>The GNU LGPL applies to the CUPS API library, located in the &quot;cups&quot;
2517  subdirectory of the CUPS source distribution and in the
2518  &quot;/usr/include/cups&quot; directory and &quot;libcups.a&quot;, &quot;libcups.sl&quot;, or
2519  &quot;libcups.so&quot; files in the binary distributions.</P>
2520 <P>The GNU GPL applies to the remainder of the CUPS distribution,
2521  including the &quot;pstoraster&quot; filter which is based upon GNU Ghostscript
2522  5.50 and the &quot;pdftops&quot; filter which is based upon Xpdf 0.92.</P>
2523 <P>For those not familiar with the GNU GPL, the license basically allows
2524  you to:</P>
2525 <UL>
2526 <LI>Use the CUPS software at no charge.</LI>
2527 <LI>Distribute verbatim copies of the software in source or binary form.</LI>
2528 <LI>Sell verbatim copies of the software for a media fee, or sell
2529  support for the software.</LI>
2530 <LI>Distribute or sell printer drivers and filters that use CUPS so long
2531  as source code is made available under the GPL.</LI>
2532 </UL>
2533 <P>What this license<B> does not</B> allow you to do is make changes or
2534  add features to CUPS and then sell a binary distribution without source
2535  code. You must provide source for any new drivers, changes, or
2536  additions to the software, and all code must be provided under the GPL
2537  or LGPL as appropriate.</P>
2538 <P>The GNU LGPL relaxes the &quot;link-to&quot; restriction, allowing you to
2539  develop applications that use the CUPS API library under other licenses
2540  and/or conditions as appropriate for your application.</P>
2541 <H3><A NAME="7_1_2">Trademarks</A></H3>
2542 <P>Easy Software Products has trademarked the Common UNIX Printing
2543  System, CUPS, and CUPS logo. These names and logos may be used freely
2544  in any direct port or binary distribution of CUPS. To use them in
2545  derivative products, please contract Easy Software Products for written
2546  permission. Our intention is to protect the value of these trademarks
2547  and ensure that any derivative product meets the same high-quality
2548  standards as the original.</P>
2549 <H3><A NAME="7_1_3">Binary Distribution Rights</A></H3>
2550 <P>Easy Software Products also sells rights to the CUPS source code
2551  under a binary distribution license for vendors that are unable to
2552  release source code for their drivers, additions, and modifications to
2553  CUPS under the GNU GPL and LGPL. For information please contact us at
2554  the address shown above.</P>
2555 <P>The Common UNIX Printing System provides a &quot;pstoraster&quot; filter that
2556  utilizes the GNU GhostScript 5.50 core to convert PostScript files into
2557  a stream of raster images. For binary distribution licensing of this
2558  software, please contact:<BLOCKQUOTE> Miles Jones
2559 <BR> Director of Marketing
2560 <BR> Artifex Software Inc.
2561 <BR> 454 Las Gallinas Ave., Suite 108
2562 <BR> San Rafael, CA 94903 USA
2563 <BR> Voice: +1.415.492.9861
2564 <BR> Fax: +1.415.492.9862
2565 <BR> EMail:<A HREF="mailto:info@arsoft.com"> info@arsoft.com</A></BLOCKQUOTE>
2566 </P>
2567 <P>The &quot;pdftops&quot; filter is based on the Xpdf 0.92 software. For binary
2568  distribution licensing of this software, please contact:<BLOCKQUOTE>
2569  Derek B. Noonburg
2570 <BR> Email:<A HREF="mailto:derekn@foolabs.com"> derekn@foolabs.com</A>
2571 <BR> WWW:<A HREF="http://www.foolabs.com/xpdf/">
2572  http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P>
2573 <H3><A NAME="7_1_4">Support</A></H3>
2574 <P>Easy Software Products sells software support for CUPS as well as a
2575  commercial printing product based on CUPS called ESP Print Pro. You can
2576  find out more at our web site:</P>
2577 <UL>
2578 <PRE>
2579 <A HREF="http://www.easysw.com">http://www.easysw.com</A>
2580 </PRE>
2581 </UL>
2582
2583 <!-- NEW PAGE -->
2584 <H2><A NAME="7_2">GNU GENERAL PUBLIC LICENSE</A></H2>
2585 <P>Version 2, June 1991</P>
2586 <PRE>
2587 Copyright 1989, 1991 Free Software Foundation, Inc.
2588 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2589
2590 Everyone is permitted to copy and distribute verbatim
2591 copies of this license document, but changing it is not allowed.
2592 </PRE>
2593 <PRE>
2594
2595 </PRE>
2596 <H4>Preamble</H4>
2597 <P>The licenses for most software are designed to take away your freedom
2598  to share and change it. By contrast, the GNU General Public License is
2599  intended to guarantee your freedom to share and change free
2600  software--to make sure the software is free for all its users. This
2601  General Public License applies to most of the Free Software
2602  Foundation's software and to any other program whose authors commit to
2603  using it. (Some other Free Software Foundation software is covered by
2604  the GNU Library General Public License instead.) You can apply it to
2605  your programs, too.</P>
2606 <P>When we speak of free software, we are referring to freedom, not
2607  price. Our General Public Licenses are designed to make sure that you
2608  have the freedom to distribute copies of free software (and charge for
2609  this service if you wish), that you receive source code or can get it
2610  if you want it, that you can change the software or use pieces of it in
2611  new free programs; and that you know you can do these things.</P>
2612 <P>To protect your rights, we need to make restrictions that forbid
2613  anyone to deny you these rights or to ask you to surrender the rights.
2614  These restrictions translate to certain responsibilities for you if you
2615  distribute copies of the software, or if you modify it.</P>
2616 <P>For example, if you distribute copies of such a program, whether
2617  gratis or for a fee, you must give the recipients all the rights that
2618  you have. You must make sure that they, too, receive or can get the
2619  source code. And you must show them these terms so they know their
2620  rights.</P>
2621 <P>We protect your rights with two steps: (1) copyright the software,
2622  and (2) offer you this license which gives you legal permission to
2623  copy, distribute and/or modify the software.</P>
2624 <P>Also, for each author's protection and ours, we want to make certain
2625  that everyone understands that there is no warranty for this free
2626  software. If the software is modified by someone else and passed on, we
2627  want its recipients to know that what they have is not the original, so
2628  that any problems introduced by others will not reflect on the original
2629  authors' reputations.</P>
2630 <P>Finally, any free program is threatened constantly by software
2631  patents. We wish to avoid the danger that redistributors of a free
2632  program will individually obtain patent licenses, in effect making the
2633  program proprietary. To prevent this, we have made it clear that any
2634  patent must be licensed for everyone's free use or not licensed at all.</P>
2635 <P>The precise terms and conditions for copying, distribution and
2636  modification follow.</P>
2637 <H4>GNU GENERAL PUBLIC LICENSE
2638 <BR> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2639 <OL START="0">
2640 <LI>This License applies to any program or other work which contains a
2641  notice placed by the copyright holder saying it may be distributed
2642  under the terms of this General Public License. The &quot;Program&quot;, below,
2643  refers to any such program or work, and a &quot;work based on the Program&quot;
2644  means either the Program or any derivative work under copyright law:
2645  that is to say, a work containing the Program or a portion of it,
2646  either verbatim or with modifications and/or translated into another
2647  language. (Hereinafter, translation is included without limitation in
2648  the term &quot;modification&quot;.) Each licensee is addressed as &quot;you&quot;.</LI>
2649 <P>Activities other than copying, distribution and modification are not
2650  covered by this License; they are outside its scope. The act of running
2651  the Program is not restricted, and the output from the Program is
2652  covered only if its contents constitute a work based on the Program
2653  (independent of having been made by running the Program). Whether that
2654  is true depends on what the Program does.</P>
2655 <LI>You may copy and distribute verbatim copies of the Program's source
2656  code as you receive it, in any medium, provided that you conspicuously
2657  and appropriately publish on each copy an appropriate copyright notice
2658  and disclaimer of warranty; keep intact all the notices that refer to
2659  this License and to the absence of any warranty; and give any other
2660  recipients of the Program a copy of this License along with the
2661  Program.</LI>
2662 <P>You may charge a fee for the physical act of transferring a copy, and
2663  you may at your option offer warranty protection in exchange for a fee.</P>
2664 <LI>You may modify your copy or copies of the Program or any portion of
2665  it, thus forming a work based on the Program, and copy and distribute
2666  such modifications or work under the terms of Section 1 above, provided
2667  that you also meet all of these conditions:
2668 <OL TYPE="a">
2669 <LI>You must cause the modified files to carry prominent notices stating
2670  that you changed the files and the date of any change.</LI>
2671 <LI>You must cause any work that you distribute or publish, that in
2672  whole or in part contains or is derived from the Program or any part
2673  thereof, to be licensed as a whole at no charge to all third parties
2674  under the terms of this License.</LI>
2675 <LI>if the modified program normally reads commands interactively when
2676  run, you must cause it, when started running for such interactive use
2677  in the most ordinary way, to print or display an announcement including
2678  an appropriate copyright notice and a notice that there is no warranty
2679  (or else, saying that you provide a warranty) and that users may
2680  redistribute the program under these conditions, and telling the user
2681  how to view a copy of this License. (Exception: if the Program itself
2682  is interactive but does not normally print such an announcement, your
2683  work based on the Program is not required to print an announcement.)</LI>
2684 </OL>
2685 </LI>
2686 <P>These requirements apply to the modified work as a whole. If
2687  identifiable sections of that work are not derived from the Program,
2688  and can be reasonably considered independent and separate works in
2689  themselves, then this License, and its terms, do not apply to those
2690  sections when you distribute them as separate works. But when you
2691  distribute the same sections as part of a whole which is a work based
2692  on the Program, the distribution of the whole must be on the terms of
2693  this License, whose permissions for other licensees extend to the
2694  entire whole, and thus to each and every part regardless of who wrote
2695  it.</P>
2696 <P>Thus, it is not the intent of this section to claim rights or contest
2697  your rights to work written entirely by you; rather, the intent is to
2698  exercise the right to control the distribution of derivative or
2699  collective works based on the Program.</P>
2700 <P>In addition, mere aggregation of another work not based on the
2701  Program with the Program (or with a work based on the Program) on a
2702  volume of a storage or distribution medium does not bring the other
2703  work under the scope of this License.</P>
2704 <LI>You may copy and distribute the Program (or a work based on it,
2705  under Section 2) in object code or executable form under the terms of
2706  Sections 1 and 2 above provided that you also do one of the following:
2707 <OL TYPE="a">
2708 <LI>Accompany it with the complete corresponding machine-readable source
2709  code, which must be distributed under the terms of Sections 1 and 2
2710  above on a medium customarily used for software interchange; or,</LI>
2711 <LI>Accompany it with a written offer, valid for at least three years,
2712  to give any third party, for a charge no more than your cost of
2713  physically performing source distribution, a complete machine-readable
2714  copy of the corresponding source code, to be distributed under the
2715  terms of Sections 1 and 2 above on a medium customarily used for
2716  software interchange; or,</LI>
2717 <LI>Accompany it with the information you received as to the offer to
2718  distribute corresponding source code. (This alternative is allowed only
2719  for noncommercial distribution and only if you received the program in
2720  object code or executable form with such an offer, in accord with
2721  Subsection b above.)</LI>
2722 </OL>
2723 </LI>
2724 <P>The source code for a work means the preferred form of the work for
2725  making modifications to it. For an executable work, complete source
2726  code means all the source code for all modules it contains, plus any
2727  associated interface definition files, plus the scripts used to control
2728  compilation and installation of the executable. However, as a special
2729  exception, the source code distributed need not include anything that
2730  is normally distributed (in either source or binary form) with the
2731  major components (compiler, kernel, and so on) of the operating system
2732  on which the executable runs, unless that component itself accompanies
2733  the executable.</P>
2734 <P>If distribution of executable or object code is made by offering
2735  access to copy from a designated place, then offering equivalent access
2736  to copy the source code from the same place counts as distribution of
2737  the source code, even though third parties are not compelled to copy
2738  the source along with the object code.</P>
2739 <LI>You may not copy, modify, sublicense, or distribute the Program
2740  except as expressly provided under this License. Any attempt otherwise
2741  to copy, modify, sublicense or distribute the Program is void, and will
2742  automatically terminate your rights under this License. However,
2743  parties who have received copies, or rights, from you under this
2744  License will not have their licenses terminated so long as such parties
2745  remain in full compliance.</LI>
2746 <LI>You are not required to accept this License, since you have not
2747  signed it. However, nothing else grants you permission to modify or
2748  distribute the Program or its derivative works. These actions are
2749  prohibited by law if you do not accept this License. Therefore, by
2750  modifying or distributing the Program (or any work based on the
2751  Program), you indicate your acceptance of this License to do so, and
2752  all its terms and conditions for copying, distributing or modifying the
2753  Program or works based on it.</LI>
2754 <LI>Each time you redistribute the Program (or any work based on the
2755  Program), the recipient automatically receives a license from the
2756  original licensor to copy, distribute or modify the Program subject to
2757  these terms and conditions. You may not impose any further restrictions
2758  on the recipients' exercise of the rights granted herein. You are not
2759  responsible for enforcing compliance by third parties to this License.</LI>
2760 <LI>If, as a consequence of a court judgment or allegation of patent
2761  infringement or for any other reason (not limited to patent issues),
2762  conditions are imposed on you (whether by court order, agreement or
2763  otherwise) that contradict the conditions of this License, they do not
2764  excuse you from the conditions of this License. If you cannot
2765  distribute so as to satisfy simultaneously your obligations under this
2766  License and any other pertinent obligations, then as a consequence you
2767  may not distribute the Program at all. For example, if a patent license
2768  would not permit royalty-free redistribution of the Program by all
2769  those who receive copies directly or indirectly through you, then the
2770  only way you could satisfy both it and this License would be to refrain
2771  entirely from distribution of the Program.</LI>
2772 <P>If any portion of this section is held invalid or unenforceable under
2773  any particular circumstance, the balance of the section is intended to
2774  apply and the section as a whole is intended to apply in other
2775  circumstances.</P>
2776 <P>It is not the purpose of this section to induce you to infringe any
2777  patents or other property right claims or to contest validity of any
2778  such claims; this section has the sole purpose of protecting the
2779  integrity of the free software distribution system, which is
2780  implemented by public license practices. Many people have made generous
2781  contributions to the wide range of software distributed through that
2782  system in reliance on consistent application of that system; it is up
2783  to the author/donor to decide if he or she is willing to distribute
2784  software through any other system and a licensee cannot impose that
2785  choice.</P>
2786 <P>This section is intended to make thoroughly clear what is believed to
2787  be a consequence of the rest of this License.</P>
2788 <LI>If the distribution and/or use of the Program is restricted in
2789  certain countries either by patents or by copyrighted interfaces, the
2790  original copyright holder who places the Program under this License may
2791  add an explicit geographical distribution limitation excluding those
2792  countries, so that distribution is permitted only in or among countries
2793  not thus excluded. In such case, this License incorporates the
2794  limitation as if written in the body of this License.</LI>
2795 <LI>The Free Software Foundation may publish revised and/or new versions
2796  of the General Public License from time to time. Such new versions will
2797  be similar in spirit to the present version, but may differ in detail
2798  to address new problems or concerns.</LI>
2799 <P>Each version is given a distinguishing version number. If the Program
2800  specifies a version number of this License which applies to it and &quot;any
2801  later version&quot;, you have the option of following the terms and
2802  conditions either of that version or of any later version published by
2803  the Free Software Foundation. If the Program does not specify a version
2804  number of this License, you may choose any version ever published by
2805  the Free Software Foundation.</P>
2806 <LI>If you wish to incorporate parts of the Program into other free
2807  programs whose distribution conditions are different, write to the
2808  author to ask for permission. For software which is copyrighted by the
2809  Free Software Foundation, write to the Free Software Foundation; we
2810  sometimes make exceptions for this. Our decision will be guided by the
2811  two goals of preserving the free status of all derivatives of our free
2812  software and of promoting the sharing and reuse of software generally.</LI>
2813 </OL>
2814 <H4>NO WARRANTY</H4>
2815 <OL START="11">
2816 <LI>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2817  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2818  OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2819  PROVIDE THE PROGRAM &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER
2820  EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
2821  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
2822  ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
2823  YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
2824  NECESSARY SERVICING, REPAIR OR CORRECTION.</LI>
2825 <LI>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
2826  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
2827  AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
2828  FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
2829  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
2830  PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
2831  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
2832  FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
2833  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
2834  DAMAGES.</LI>
2835 </OL>
2836 <H4>END OF TERMS AND CONDITIONS</H4>
2837
2838 <!-- NEW PAGE -->
2839 <H2><A NAME="7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2>
2840 <P>Version 2, June 1991</P>
2841 <PRE>
2842 Copyright (C) 1991 Free Software Foundation, Inc.
2843 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
2844 Everyone is permitted to copy and distribute verbatim copies
2845 of this license document, but changing it is not allowed.
2846
2847 [This is the first released version of the library GPL.  It is
2848  numbered 2 because it goes with version 2 of the ordinary GPL.]
2849 </PRE>
2850 <H4>Preamble</H4>
2851 <P>The licenses for most software are designed to take away your freedom
2852  to share and change it. By contrast, the GNU General Public Licenses
2853  are intended to guarantee your freedom to share and change free
2854  software--to make sure the software is free for all its users.</P>
2855 <P>This license, the Library General Public License, applies to some
2856  specially designated Free Software Foundation software, and to any
2857  other libraries whose authors decide to use it. You can use it for your
2858  libraries, too.</P>
2859 <P>When we speak of free software, we are referring to freedom, not
2860  price. Our General Public Licenses are designed to make sure that you
2861  have the freedom to distribute copies of free software (and charge for
2862  this service if you wish), that you receive source code or can get it
2863  if you want it, that you can change the software or use pieces of it in
2864  new free programs; and that you know you can do these things.</P>
2865 <P>To protect your rights, we need to make restrictions that forbid
2866  anyone to deny you these rights or to ask you to surrender the rights.
2867  These restrictions translate to certain responsibilities for you if you
2868  distribute copies of the library, or if you modify it.</P>
2869 <P>For example, if you distribute copies of the library, whether gratis
2870  or for a fee, you must give the recipients all the rights that we gave
2871  you. You must make sure that they, too, receive or can get the source
2872  code. If you link a program with the library, you must provide complete
2873  object files to the recipients so that they can relink them with the
2874  library, after making changes to the library and recompiling it. And
2875  you must show them these terms so they know their rights.</P>
2876 <P>Our method of protecting your rights has two steps: (1) copyright the
2877  library, and (2) offer you this license which gives you legal
2878  permission to copy, distribute and/or modify the library.</P>
2879 <P>Also, for each distributor's protection, we want to make certain that
2880  everyone understands that there is no warranty for this free library.
2881  If the library is modified by someone else and passed on, we want its
2882  recipients to know that what they have is not the original version, so
2883  that any problems introduced by others will not reflect on the original
2884  authors' reputations.</P>
2885 <P>Finally, any free program is threatened constantly by software
2886  patents. We wish to avoid the danger that companies distributing free
2887  software will individually obtain patent licenses, thus in effect
2888  transforming the program into proprietary software. To prevent this, we
2889  have made it clear that any patent must be licensed for everyone's free
2890  use or not licensed at all.</P>
2891 <P>Most GNU software, including some libraries, is covered by the
2892  ordinary GNU General Public License, which was designed for utility
2893  programs. This license, the GNU Library General Public License, applies
2894  to certain designated libraries. This license is quite different from
2895  the ordinary one; be sure to read it in full, and don't assume that
2896  anything in it is the same as in the ordinary license.</P>
2897 <P>The reason we have a separate public license for some libraries is
2898  that they blur the distinction we usually make between modifying or
2899  adding to a program and simply using it. Linking a program with a
2900  library, without changing the library, is in some sense simply using
2901  the library, and is analogous to running a utility program or
2902  application program. However, in a textual and legal sense, the linked
2903  executable is a combined work, a derivative of the original library,
2904  and the ordinary General Public License treats it as such.</P>
2905 <P>Because of this blurred distinction, using the ordinary General
2906  Public License for libraries did not effectively promote software
2907  sharing, because most developers did not use the libraries. We
2908  concluded that weaker conditions might promote sharing better.</P>
2909 <P>However, unrestricted linking of non-free programs would deprive the
2910  users of those programs of all benefit from the free status of the
2911  libraries themselves. This Library General Public License is intended
2912  to permit developers of non-free programs to use free libraries, while
2913  preserving your freedom as a user of such programs to change the free
2914  libraries that are incorporated in them. (We have not seen how to
2915  achieve this as regards changes in header files, but we have achieved
2916  it as regards changes in the actual functions of the Library.) The hope
2917  is that this will lead to faster development of free libraries.</P>
2918 <P>The precise terms and conditions for copying, distribution and
2919  modification follow. Pay close attention to the difference between a
2920  &quot;work based on the library&quot; and a &quot;work that uses the library&quot;. The
2921  former contains code derived from the library, while the latter only
2922  works together with the library.</P>
2923 <P>Note that it is possible for a library to be covered by the ordinary
2924  General Public License rather than by this special one.</P>
2925 <H4>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2926 <P><STRONG>0.</STRONG> This License Agreement applies to any software
2927  library which contains a notice placed by the copyright holder or other
2928  authorized party saying it may be distributed under the terms of this
2929  Library General Public License (also called &quot;this License&quot;). Each
2930  licensee is addressed as &quot;you&quot;.</P>
2931 <P>A &quot;library&quot; means a collection of software functions and/or data
2932  prepared so as to be conveniently linked with application programs
2933  (which use some of those functions and data) to form executables.</P>
2934 <P>The &quot;Library&quot;, below, refers to any such software library or work
2935  which has been distributed under these terms. A &quot;work based on the
2936  Library&quot; means either the Library or any derivative work under
2937  copyright law: that is to say, a work containing the Library or a
2938  portion of it, either verbatim or with modifications and/or translated
2939  straightforwardly into another language. (Hereinafter, translation is
2940  included without limitation in the term &quot;modification&quot;.)</P>
2941 <P>&quot;Source code&quot; for a work means the preferred form of the work for
2942  making modifications to it. For a library, complete source code means
2943  all the source code for all modules it contains, plus any associated
2944  interface definition files, plus the scripts used to control
2945  compilation and installation of the library.</P>
2946 <P>Activities other than copying, distribution and modification are not
2947  covered by this License; they are outside its scope. The act of running
2948  a program using the Library is not restricted, and output from such a
2949  program is covered only if its contents constitute a work based on the
2950  Library (independent of the use of the Library in a tool for writing
2951  it). Whether that is true depends on what the Library does and what the
2952  program that uses the Library does.</P>
2953 <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
2954  the Library's complete source code as you receive it, in any medium,
2955  provided that you conspicuously and appropriately publish on each copy
2956  an appropriate copyright notice and disclaimer of warranty; keep intact
2957  all the notices that refer to this License and to the absence of any
2958  warranty; and distribute a copy of this License along with the Library.</P>
2959 <P>You may charge a fee for the physical act of transferring a copy, and
2960  you may at your option offer warranty protection in exchange for a fee.</P>
2961 <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library
2962  or any portion of it, thus forming a work based on the Library, and
2963  copy and distribute such modifications or work under the terms of
2964  Section 1 above, provided that you also meet all of these conditions:</P>
2965 <OL TYPE="a">
2966 <LI>The modified work must itself be a software library.</LI>
2967 <P></P>
2968 <LI>You must cause the files modified to carry prominent notices stating
2969  that you changed the files and the date of any change.</LI>
2970 <P></P>
2971 <LI>You must cause the whole of the work to be licensed at no charge to
2972  all third parties under the terms of this License.</LI>
2973 <P></P>
2974 <LI>If a facility in the modified Library refers to a function or a
2975  table of data to be supplied by an application program that uses the
2976  facility, other than as an argument passed when the facility is
2977  invoked, then you must make a good faith effort to ensure that, in the
2978  event an application does not supply such function or table, the
2979  facility still operates, and performs whatever part of its purpose
2980  remains meaningful.</LI>
2981 <P>(For example, a function in a library to compute square roots has a
2982  purpose that is entirely well-defined independent of the application.
2983  Therefore, Subsection 2d requires that any application-supplied
2984  function or table used by this function must be optional: if the
2985  application does not supply it, the square root function must still
2986  compute square roots.)</P>
2987 </OL>
2988 <P>These requirements apply to the modified work as a whole. If
2989  identifiable sections of that work are not derived from the Library,
2990  and can be reasonably considered independent and separate works in
2991  themselves, then this License, and its terms, do not apply to those
2992  sections when you distribute them as separate works. But when you
2993  distribute the same sections as part of a whole which is a work based
2994  on the Library, the distribution of the whole must be on the terms of
2995  this License, whose permissions for other licensees extend to the
2996  entire whole, and thus to each and every part regardless of who wrote
2997  it.</P>
2998 <P>Thus, it is not the intent of this section to claim rights or contest
2999  your rights to work written entirely by you; rather, the intent is to
3000  exercise the right to control the distribution of derivative or
3001  collective works based on the Library.</P>
3002 <P>In addition, mere aggregation of another work not based on the
3003  Library with the Library (or with a work based on the Library) on a
3004  volume of a storage or distribution medium does not bring the other
3005  work under the scope of this License.</P>
3006 <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
3007  GNU General Public License instead of this License to a given copy of
3008  the Library. To do this, you must alter all the notices that refer to
3009  this License, so that they refer to the ordinary GNU General Public
3010  License, version 2, instead of to this License. (If a newer version
3011  than version 2 of the ordinary GNU General Public License has appeared,
3012  then you can specify that version instead if you wish.) Do not make any
3013  other change in these notices.</P>
3014 <P>Once this change is made in a given copy, it is irreversible for that
3015  copy, so the ordinary GNU General Public License applies to all
3016  subsequent copies and derivative works made from that copy.</P>
3017 <P>This option is useful when you wish to copy part of the code of the
3018  Library into a program that is not a library.</P>
3019 <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
3020  portion or derivative of it, under Section 2) in object code or
3021  executable form under the terms of Sections 1 and 2 above provided that
3022  you accompany it with the complete corresponding machine-readable
3023  source code, which must be distributed under the terms of Sections 1
3024  and 2 above on a medium customarily used for software interchange.</P>
3025 <P>If distribution of object code is made by offering access to copy
3026  from a designated place, then offering equivalent access to copy the
3027  source code from the same place satisfies the requirement to distribute
3028  the source code, even though third parties are not compelled to copy
3029  the source along with the object code.</P>
3030 <P><STRONG>5.</STRONG> A program that contains no derivative of any
3031  portion of the Library, but is designed to work with the Library by
3032  being compiled or linked with it, is called a &quot;work that uses the
3033  Library&quot;. Such a work, in isolation, is not a derivative work of the
3034  Library, and therefore falls outside the scope of this License.</P>
3035 <P>However, linking a &quot;work that uses the Library&quot; with the Library
3036  creates an executable that is a derivative of the Library (because it
3037  contains portions of the Library), rather than a &quot;work that uses the
3038  library&quot;. The executable is therefore covered by this License. Section
3039  6 states terms for distribution of such executables.</P>
3040 <P>When a &quot;work that uses the Library&quot; uses material from a header file
3041  that is part of the Library, the object code for the work may be a
3042  derivative work of the Library even though the source code is not.
3043  Whether this is true is especially significant if the work can be
3044  linked without the Library, or if the work is itself a library. The
3045  threshold for this to be true is not precisely defined by law.</P>
3046 <P>If such an object file uses only numerical parameters, data structure
3047  layouts and accessors, and small macros and small inline functions (ten
3048  lines or less in length), then the use of the object file is
3049  unrestricted, regardless of whether it is legally a derivative work.
3050  (Executables containing this object code plus portions of the Library
3051  will still fall under Section 6.)</P>
3052 <P>Otherwise, if the work is a derivative of the Library, you may
3053  distribute the object code for the work under the terms of Section 6.
3054  Any executables containing that work also fall under Section 6, whether
3055  or not they are linked directly with the Library itself.</P>
3056 <P><STRONG>6.</STRONG> As an exception to the Sections above, you may
3057  also compile or link a &quot;work that uses the Library&quot; with the Library to
3058  produce a work containing portions of the Library, and distribute that
3059  work under terms of your choice, provided that the terms permit
3060  modification of the work for the customer's own use and reverse
3061  engineering for debugging such modifications.</P>
3062 <P>You must give prominent notice with each copy of the work that the
3063  Library is used in it and that the Library and its use are covered by
3064  this License. You must supply a copy of this License. If the work
3065  during execution displays copyright notices, you must include the
3066  copyright notice for the Library among them, as well as a reference
3067  directing the user to the copy of this License. Also, you must do one
3068  of these things:</P>
3069 <OL TYPE="a">
3070 <LI>Accompany the work with the complete corresponding machine-readable
3071  source code for the Library including whatever changes were used in the
3072  work (which must be distributed under Sections 1 and 2 above); and, if
3073  the work is an executable linked with the Library, with the complete
3074  machine-readable &quot;work that uses the Library&quot;, as object code and/or
3075  source code, so that the user can modify the Library and then relink to
3076  produce a modified executable containing the modified Library. (It is
3077  understood that the user who changes the contents of definitions files
3078  in the Library will not necessarily be able to recompile the
3079  application to use the modified definitions.)</LI>
3080 <P></P>
3081 <LI>Accompany the work with a written offer, valid for at least three
3082  years, to give the same user the materials specified in Subsection 6a,
3083  above, for a charge no more than the cost of performing this
3084  distribution.</LI>
3085 <P></P>
3086 <LI>If distribution of the work is made by offering access to copy from
3087  a designated place, offer equivalent access to copy the above specified
3088  materials from the same place.</LI>
3089 <P></P>
3090 <LI>Verify that the user has already received a copy of these materials
3091  or that you have already sent this user a copy.</LI>
3092 </OL>
3093 <P>For an executable, the required form of the &quot;work that uses the
3094  Library&quot; must include any data and utility programs needed for
3095  reproducing the executable from it. However, as a special exception,
3096  the source code distributed need not include anything that is normally
3097  distributed (in either source or binary form) with the major components
3098  (compiler, kernel, and so on) of the operating system on which the
3099  executable runs, unless that component itself accompanies the
3100  executable.</P>
3101 <P>It may happen that this requirement contradicts the license
3102  restrictions of other proprietary libraries that do not normally
3103  accompany the operating system. Such a contradiction means you cannot
3104  use both them and the Library together in an executable that you
3105  distribute.</P>
3106 <P><STRONG>7.</STRONG> You may place library facilities that are a work
3107  based on the Library side-by-side in a single library together with
3108  other library facilities not covered by this License, and distribute
3109  such a combined library, provided that the separate distribution of the
3110  work based on the Library and of the other library facilities is
3111  otherwise permitted, and provided that you do these two things:</P>
3112 <OL TYPE="a">
3113 <LI>Accompany the combined library with a copy of the same work based on
3114  the Library, uncombined with any other library facilities. This must be
3115  distributed under the terms of the Sections above.</LI>
3116 <P></P>
3117 <LI>Give prominent notice with the combined library of the fact that
3118  part of it is a work based on the Library, and explaining where to find
3119  the accompanying uncombined form of the same work.</LI>
3120 </OL>
3121 <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with,
3122  or distribute the Library except as expressly provided under this
3123  License. Any attempt otherwise to copy, modify, sublicense, link with,
3124  or distribute the Library is void, and will automatically terminate
3125  your rights under this License. However, parties who have received
3126  copies, or rights, from you under this License will not have their
3127  licenses terminated so long as such parties remain in full compliance.</P>
3128 <P><STRONG>9.</STRONG> You are not required to accept this License,
3129  since you have not signed it. However, nothing else grants you
3130  permission to modify or distribute the Library or its derivative works.
3131  These actions are prohibited by law if you do not accept this License.
3132  Therefore, by modifying or distributing the Library (or any work based
3133  on the Library), you indicate your acceptance of this License to do so,
3134  and all its terms and conditions for copying, distributing or modifying
3135  the Library or works based on it.</P>
3136 <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
3137  work based on the Library), the recipient automatically receives a
3138  license from the original licensor to copy, distribute, link with or
3139  modify the Library subject to these terms and conditions. You may not
3140  impose any further restrictions on the recipients' exercise of the
3141  rights granted herein. You are not responsible for enforcing compliance
3142  by third parties to this License.</P>
3143 <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
3144  allegation of patent infringement or for any other reason (not limited
3145  to patent issues), conditions are imposed on you (whether by court
3146  order, agreement or otherwise) that contradict the conditions of this
3147  License, they do not excuse you from the conditions of this License. If
3148  you cannot distribute so as to satisfy simultaneously your obligations
3149  under this License and any other pertinent obligations, then as a
3150  consequence you may not distribute the Library at all. For example, if
3151  a patent license would not permit royalty-free redistribution of the
3152  Library by all those who receive copies directly or indirectly through
3153  you, then the only way you could satisfy both it and this License would
3154  be to refrain entirely from distribution of the Library.</P>
3155 <P>If any portion of this section is held invalid or unenforceable under
3156  any particular circumstance, the balance of the section is intended to
3157  apply, and the section as a whole is intended to apply in other
3158  circumstances.</P>
3159 <P>It is not the purpose of this section to induce you to infringe any
3160  patents or other property right claims or to contest validity of any
3161  such claims; this section has the sole purpose of protecting the
3162  integrity of the free software distribution system which is implemented
3163  by public license practices. Many people have made generous
3164  contributions to the wide range of software distributed through that
3165  system in reliance on consistent application of that system; it is up
3166  to the author/donor to decide if he or she is willing to distribute
3167  software through any other system and a licensee cannot impose that
3168  choice.</P>
3169 <P>This section is intended to make thoroughly clear what is believed to
3170  be a consequence of the rest of this License.</P>
3171 <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is
3172  restricted in certain countries either by patents or by copyrighted
3173  interfaces, the original copyright holder who places the Library under
3174  this License may add an explicit geographical distribution limitation
3175  excluding those countries, so that distribution is permitted only in or
3176  among countries not thus excluded. In such case, this License
3177  incorporates the limitation as if written in the body of this License.</P>
3178 <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised
3179  and/or new versions of the Library General Public License from time to
3180  time. Such new versions will be similar in spirit to the present
3181  version, but may differ in detail to address new problems or concerns.</P>
3182 <P>Each version is given a distinguishing version number. If the Library
3183  specifies a version number of this License which applies to it and &quot;any
3184  later version&quot;, you have the option of following the terms and
3185  conditions either of that version or of any later version published by
3186  the Free Software Foundation. If the Library does not specify a license
3187  version number, you may choose any version ever published by the Free
3188  Software Foundation.</P>
3189 <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
3190  into other free programs whose distribution conditions are incompatible
3191  with these, write to the author to ask for permission. For software
3192  which is copyrighted by the Free Software Foundation, write to the Free
3193  Software Foundation; we sometimes make exceptions for this. Our
3194  decision will be guided by the two goals of preserving the free status
3195  of all derivatives of our free software and of promoting the sharing
3196  and reuse of software generally.</P>
3197 <P><STRONG>NO WARRANTY</STRONG></P>
3198 <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
3199  THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
3200  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
3201  HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
3202  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
3203  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
3204  PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
3205  OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
3206  ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
3207 <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
3208  AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
3209  MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
3210  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
3211  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
3212  LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
3213  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
3214  FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
3215  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
3216  DAMAGES.</P>
3217 <H4>END OF TERMS AND CONDITIONS</H4>
3218 <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
3219 <P>This appendix lists all of the constants that are defined by the CUPS
3220  API.</P>
3221 <H2><A NAME="8_1">CUPS Constants</A></H2>
3222 <H3><A NAME="8_1_1">Version Number</A></H3>
3223 <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
3224  representing the API version number. The current version number is
3225  1.0100 which represents CUPS version 1.1.0.</P>
3226 <H3><A NAME="8_1_2">Printer Capabilities</A></H3>
3227 <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
3228  printers and classes:</P>
3229 <UL>
3230 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.</LI>
3231 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.</LI>
3232 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.</LI>
3233 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.</LI>
3234 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.</LI>
3235 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.</LI>
3236 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.</LI>
3237 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
3238  copies on its own.</LI>
3239 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.</LI>
3240 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.</LI>
3241 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.</LI>
3242 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.</LI>
3243 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.</LI>
3244 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up to
3245  9x14 inches.</LI>
3246 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media from
3247  9x14 to 18x24 inches.</LI>
3248 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media larger
3249  than 18x24 inches.</LI>
3250 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on variable
3251  or custom media sizes.</LI>
3252 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.</LI>
3253 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
3254  and option bits.</LI>
3255 </UL>
3256 <H3><A NAME="8_1_3">Encodings</A></H3>
3257 <P>CUPS defines the following character set encoding constants:</P>
3258 <UL>
3259 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.</LI>
3260 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.</LI>
3261 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.</LI>
3262 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.</LI>
3263 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.</LI>
3264 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.</LI>
3265 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.</LI>
3266 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.</LI>
3267 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.</LI>
3268 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.</LI>
3269 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.</LI>
3270 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.</LI>
3271 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.</LI>
3272 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.</LI>
3273 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.</LI>
3274 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.</LI>
3275 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.</LI>
3276 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.</LI>
3277 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.</LI>
3278 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.</LI>
3279 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.</LI>
3280 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.</LI>
3281 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.</LI>
3282 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.</LI>
3283 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.</LI>
3284 </UL>
3285 <H2><A NAME="8_2">HTTP Constants</A></H2>
3286 <H3><A NAME="8_2_1">Limits</A></H3>
3287 <P>The following constants define the limits for strings:</P>
3288 <UL>
3289 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.</LI>
3290 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.</LI>
3291 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.</LI>
3292 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.</LI>
3293 </UL>
3294 <H3><A NAME="8_2_2">Status Codes</A></H3>
3295 <P>The following status codes can be returned by <CODE>httpUpdate()</CODE>
3296 :</P>
3297 <UL>
3298 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred</LI>
3299 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy</LI>
3300 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was
3301  successful</LI>
3302 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful</LI>
3303 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful</LI>
3304 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't
3305  authoritative</LI>
3306 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command</LI>
3307 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated</LI>
3308 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was
3309  recieved/sent</LI>
3310 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request</LI>
3311 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently</LI>
3312 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily</LI>
3313 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...</LI>
3314 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified</LI>
3315 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI</LI>
3316 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request</LI>
3317 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host</LI>
3318 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required</LI>
3319 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI</LI>
3320 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found</LI>
3321 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed</LI>
3322 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable</LI>
3323 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is
3324  Required</LI>
3325 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out</LI>
3326 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting</LI>
3327 <LI><CODE>HTTP_GONE</CODE> - Server has gone away</LI>
3328 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is
3329  required</LI>
3330 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed</LI>
3331 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large</LI>
3332 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long</LI>
3333 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type
3334  is unsupported</LI>
3335 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error</LI>
3336 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented</LI>
3337 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway</LI>
3338 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable</LI>
3339 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out</LI>
3340 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported</LI>
3341 </UL>
3342 <H3><A NAME="8_2_3">Fields</A></H3>
3343 <P>The following fields are indices for each of the standard HTTP fields
3344  in HTTP 1/1:</P>
3345 <UL>
3346 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language</LI>
3347 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges</LI>
3348 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization</LI>
3349 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection</LI>
3350 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding</LI>
3351 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language</LI>
3352 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length</LI>
3353 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location</LI>
3354 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5</LI>
3355 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range</LI>
3356 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type</LI>
3357 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version</LI>
3358 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date</LI>
3359 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host</LI>
3360 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since</LI>
3361 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since</LI>
3362 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive</LI>
3363 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified</LI>
3364 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link</LI>
3365 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location</LI>
3366 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range</LI>
3367 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer</LI>
3368 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After</LI>
3369 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding</LI>
3370 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade</LI>
3371 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent</LI>
3372 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate</LI>
3373 </UL>
3374 <H2><A NAME="8_3">IPP Constants</A></H2>
3375 <H3><A NAME="8_3_1">Limits</A></H3>
3376 <P>The following constants define array limits for IPP data:</P>
3377 <UL>
3378 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name</LI>
3379 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values that
3380  can be read in a request.</LI>
3381 </UL>
3382 <H3><A NAME="8_3_2">Tags</A></H3>
3383 <UL>
3384 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
3385  used to separate groups of attributes</LI>
3386 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation</LI>
3387 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job</LI>
3388 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end</LI>
3389 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer</LI>
3390 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type
3391  unsupported_group</LI>
3392 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type
3393  unsupported_value</LI>
3394 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default</LI>
3395 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown</LI>
3396 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue</LI>
3397 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type
3398  notsettable</LI>
3399 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr</LI>
3400 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue</LI>
3401 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer</LI>
3402 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean</LI>
3403 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum</LI>
3404 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string</LI>
3405 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date</LI>
3406 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution</LI>
3407 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range</LI>
3408 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection</LI>
3409 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang</LI>
3410 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang</LI>
3411 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text</LI>
3412 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name</LI>
3413 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword</LI>
3414 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri</LI>
3415 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme</LI>
3416 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset</LI>
3417 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language</LI>
3418 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype</LI>
3419 </UL>
3420 <H3><A NAME="8_3_3">Resolution Units</A></H3>
3421 <P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE>
3422  constants specify dots per inch and dots per centimeter, respectively.</P>
3423 <H3><A NAME="8_3_4">Finishings</A></H3>
3424 <P>The finishing values specify special finishing operations to be
3425  performed on the job.</P>
3426 <UL>
3427 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing</LI>
3428 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job</LI>
3429 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job</LI>
3430 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job</LI>
3431 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job</LI>
3432 </UL>
3433 <H3><A NAME="8_3_5">Orientations</A></H3>
3434 <P>The orientation values specify the orientation of the job.</P>
3435 <UL>
3436 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation</LI>
3437 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise</LI>
3438 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise</LI>
3439 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees</LI>
3440 </UL>
3441 <H3><A NAME="8_3_6">Qualities</A></H3>
3442 <P>The quality values specify the desired quality of the print.</P>
3443 <UL>
3444 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality</LI>
3445 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality</LI>
3446 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality</LI>
3447 </UL>
3448 <H3><A NAME="8_3_7">Job States</A></H3>
3449 <P>The job state values are used to represent the current job state.</P>
3450 <UL>
3451 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending</LI>
3452 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held</LI>
3453 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing</LI>
3454 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped</LI>
3455 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled</LI>
3456 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted</LI>
3457 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed</LI>
3458 </UL>
3459 <H3><A NAME="8_3_8">Printer States</A></H3>
3460 <P>The printer state values are used to represent the current printer
3461  state.</P>
3462 <UL>
3463 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle</LI>
3464 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing</LI>
3465 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped</LI>
3466 </UL>
3467 <H3><A NAME="8_3_9">Operations</A></H3>
3468 <P>The operation values represent the available IPP operations.</P>
3469 <UL>
3470 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file</LI>
3471 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI</LI>
3472 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes</LI>
3473 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job</LI>
3474 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job</LI>
3475 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job</LI>
3476 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job</LI>
3477 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes</LI>
3478 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs</LI>
3479 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes</LI>
3480 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job</LI>
3481 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job</LI>
3482 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job</LI>
3483 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer</LI>
3484 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer</LI>
3485 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue</LI>
3486 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes</LI>
3487 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes</LI>
3488 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer
3489  supported values</LI>
3490 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination</LI>
3491 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers</LI>
3492 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer</LI>
3493 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer</LI>
3494 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes</LI>
3495 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class</LI>
3496 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class</LI>
3497 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class</LI>
3498 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class</LI>
3499 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination</LI>
3500 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices</LI>
3501 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs</LI>
3502 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination</LI>
3503 </UL>
3504 <H3><A NAME="8_3_10">Status Codes</A></H3>
3505 <P>Status codes are returned by all IPP requests.</P>
3506 <UL>
3507 <LI><CODE>IPP_OK</CODE> - Request completed with no errors</LI>
3508 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
3509  values were substituted</LI>
3510 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
3511  conflicted</LI>
3512 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad</LI>
3513 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource</LI>
3514 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
3515  the resource</LI>
3516 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access the
3517  resource</LI>
3518 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
3519  completed</LI>
3520 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred</LI>
3521 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found</LI>
3522 <LI><CODE>IPP_GONE</CODE> - The resource has gone away</LI>
3523 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large</LI>
3524 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value that
3525  was unknown to the server</LI>
3526 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
3527  supported by the server</LI>
3528 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing</LI>
3529 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported</LI>
3530 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported</LI>
3531 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict</LI>
3532 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
3533  compression is not supported</LI>
3534 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data contained
3535  an error</LI>
3536 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data contained
3537  an error in it</LI>
3538 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document could
3539  not be accessed</LI>
3540 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an internal
3541  error</LI>
3542 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
3543  is not supported</LI>
3544 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service is
3545  unavailable</LI>
3546 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request version is
3547  not supported</LI>
3548 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered an
3549  error</LI>
3550 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred</LI>
3551 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
3552  jobs</LI>
3553 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy</LI>
3554 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
3555  cancelled</LI>
3556 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server does not
3557  support multiple jobs</LI>
3558 </UL>
3559 <H2><A NAME="8_4">PPD Constants</A></H2>
3560 <H3><A NAME="8_4_1">PPD Format Version</A></H3>
3561 <P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
3562  representing the newest format version that is supported by CUPS,
3563  currently 4.3.</P>
3564 <H3><A NAME="8_4_2">PPD User-Interface Types</A></H3>
3565 <P>Each printer option has a type associated with it:</P>
3566 <UL>
3567 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or
3568  off</LI>
3569 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
3570  to use.</LI>
3571 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
3572  option values.</LI>
3573 </UL>
3574 <H3><A NAME="8_4_3">PPD Sections</A></H3>
3575 <P>Some options must be output before others, or in different sections
3576  of the output document. The <CODE>ppd_section_t</CODE> enumeration
3577  defines which section the option must be output in:</P>
3578 <UL>
3579 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of the
3580  document, page, or prolog sections of the document</LI>
3581 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in the
3582  DocumentSetup section of the document</LI>
3583 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before the
3584  document</LI>
3585 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the job
3586  control section of the document</LI>
3587 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
3588  PageSetup section of the document</LI>
3589 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
3590  Prolog section of the document</LI>
3591 </UL>
3592 <H3><A NAME="8_4_4">PPD Colorspaces</A></H3>
3593 <P>Each printer has a default colorspace:</P>
3594 <UL>
3595 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default</LI>
3596 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default</LI>
3597 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default</LI>
3598 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default</LI>
3599 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default</LI>
3600 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace by
3601  default</LI>
3602 </UL>
3603 <H2><A NAME="8_5">Raster Constants</A></H2>
3604 <H3><A NAME="8_5_1">Raster Sync Words</A></H3>
3605 <P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
3606  constants define the standard sync words at the beginning of each CUPS
3607  raster file.</P>
3608 <H3><A NAME="8_5_2">Raster Stream Modes</A></H3>
3609 <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
3610  constants are used with the<A HREF="#cupsRasterOpen"> <CODE>
3611 cupsRasterOpen()</CODE></A> function to specify a stream for reading or
3612  writing.</P>
3613 <H3><A NAME="8_5_3">Raster Boolean Constants</A></H3>
3614 <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
3615  represent boolean values in the page header.</P>
3616 <H3><A NAME="8_5_4">Raster Jog Values</A></H3>
3617 <P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the Jog
3618  page device dictionary variable:</P>
3619 <UL>
3620 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging</LI>
3621 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file</LI>
3622 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job</LI>
3623 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs</LI>
3624 </UL>
3625 <H3><A NAME="8_5_5">Raster Orientation Values</A></H3>
3626 <P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
3627  Orientation page device dictionary variable:</P>
3628 <UL>
3629 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation</LI>
3630 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation</LI>
3631 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation</LI>
3632 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation</LI>
3633 </UL>
3634 <H3><A NAME="8_5_6">Raster CutMedia Values</A></H3>
3635 <P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
3636  CutMedia page device dictionary variable:</P>
3637 <UL>
3638 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging</LI>
3639 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file</LI>
3640 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job</LI>
3641 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs</LI>
3642 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page</LI>
3643 </UL>
3644 <H3><A NAME="8_5_7">Raster AdvanceMedia Values</A></H3>
3645 <P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
3646  AdvanceMedia page device dictionary variable:</P>
3647 <UL>
3648 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging</LI>
3649 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file</LI>
3650 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job</LI>
3651 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs</LI>
3652 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page</LI>
3653 </UL>
3654 <H3><A NAME="8_5_8">Raster LeadingEdge Values</A></H3>
3655 <P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
3656  LeadingEdge page device dictionary variable:</P>
3657 <UL>
3658 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
3659  edge</LI>
3660 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
3661  edge</LI>
3662 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
3663  leading edge</LI>
3664 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
3665  edge</LI>
3666 </UL>
3667 <H3><A NAME="8_5_9">Raster Color Order Values</A></H3>
3668 <P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
3669  value orderings:</P>
3670 <UL>
3671 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
3672 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
3673 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
3674 </UL>
3675 <H3><A NAME="8_5_10">Raster Colorspace Values</A></H3>
3676 <P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible
3677  colorspaces:</P>
3678 <UL>
3679 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
3680 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
3681 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
3682 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
3683 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
3684 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
3685 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
3686 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
3687 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
3688 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
3689  light cyan, light magenta</LI>
3690 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
3691  magenta, metallic cyan, black</LI>
3692 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
3693  magenta, metallic cyan, metallic grey (silver)</LI>
3694 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
3695  pigment)</LI>
3696 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
3697 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
3698 </UL>
3699 <H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
3700 <P>This appendix describes all of the structures that are defined by the
3701  CUPS API.</P>
3702 <H2><A NAME="9_1">Raster Structures</A></H2>
3703 <H3><A NAME="9_1_1">Raster Page Header</A></H3>
3704 <P>The raster page header consists of the PostScript page device
3705  dictionary for the page:
3706 <CENTER>
3707 <TABLE BORDER="1" WIDTH="90%">
3708 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3709 <TR><TD>MediaClass</TD><TD>char[64]</TD><TD>The media class name</TD></TR>
3710 <TR><TD>MediaColor</TD><TD>char[64]</TD><TD>The media color name</TD></TR>
3711 <TR><TD>MediaType</TD><TD>char[64]</TD><TD>The media type name</TD></TR>
3712 <TR><TD>OutputType</TD><TD>char[64]</TD><TD>The output type name</TD></TR>
3713 <TR><TD>AdvanceDistance</TD><TD>unsigned</TD><TD>The distance to advance
3714  the media in points</TD></TR>
3715 <TR><TD>AdvanceMedia</TD><TD>cups_adv_t</TD><TD>When to advance the
3716  media</TD></TR>
3717 <TR><TD>Collate</TD><TD>cups_bool_t</TD><TD>Whether or not to produce
3718  collated copies</TD></TR>
3719 <TR><TD>CutMedia</TD><TD>cups_cut_t</TD><TD>When to cut the media</TD></TR>
3720 <TR><TD>Duplex</TD><TD>cups_bool_t</TD><TD>Whether or not to print on
3721  both sides of the paper</TD></TR>
3722 <TR><TD>HWResolution</TD><TD>unsigned[2]</TD><TD>The resolution of the
3723  page image in pixels per inch; the HWResolution[0] represents the
3724  horizontal resolution and HWResolution[1] represents the vertical
3725  resolution</TD></TR>
3726 <TR><TD>ImagingBoundingBox</TD><TD>unsigned[4]</TD><TD>The bounding box
3727  for the page in points; the elements represent the left, bottom, right,
3728  and top coordinates of the imaged area (if 0 then the whole page is
3729  imaged)</TD></TR>
3730 <TR><TD>InsertSheet</TD><TD>cups_bool_t</TD><TD>Whether or not to insert
3731  a sheet before this page</TD></TR>
3732 <TR><TD>Jog</TD><TD>cups_jog_t</TD><TD>When to jog copies of the page</TD>
3733 </TR>
3734 <TR><TD>LeadingEdge</TD><TD>cups_edge_t</TD><TD>The leading edge of the
3735  page</TD></TR>
3736 <TR><TD>Margins</TD><TD>unsigned[2]</TD><TD>The lower-lefthand margin of
3737  the page in points</TD></TR>
3738 <TR><TD>ManualFeed</TD><TD>cups_bool_t</TD><TD>Whether or not to
3739  manually feed the page</TD></TR>
3740 <TR><TD>MediaPosition</TD><TD>unsigned</TD><TD>The input slot number to
3741  use</TD></TR>
3742 <TR><TD>MediaWeight</TD><TD>unsigned</TD><TD>The weight of the output
3743  media in grams/m<SUP>2</SUP></TD></TR>
3744 <TR><TD>MirrorPrint</TD><TD>cups_bool_t</TD><TD>Whether or not to mirror
3745  the print</TD></TR>
3746 <TR><TD>NegativePrint</TD><TD>cups_bool_t</TD><TD>Whether or not to
3747  invert the print</TD></TR>
3748 <TR><TD>NumCopies</TD><TD>unsigned</TD><TD>The number of copies to
3749  produce</TD></TR>
3750 <TR><TD>Orientation</TD><TD>cups_orient_t</TD><TD>The orientation of the
3751  page image</TD></TR>
3752 <TR><TD>OutputFaceUp</TD><TD>cups_bool_t</TD><TD>Whether or not to
3753  output the page face up</TD></TR>
3754 <TR><TD>PageSize</TD><TD>unsigned[2]</TD><TD>The width and height of the
3755  page in points</TD></TR>
3756 <TR><TD>Separations</TD><TD>cups_bool_t</TD><TD>Whether or not to output
3757  separations</TD></TR>
3758 <TR><TD>TraySwitch</TD><TD>cups_bool_t</TD><TD>Whether or not to
3759  automatically switch trays for the requested media size/type</TD></TR>
3760 <TR><TD>Tumble</TD><TD>cups_bool_t</TD><TD>Whether or not to rotate the
3761  back side of the page</TD></TR>
3762 <TR><TD>cupsWidth</TD><TD>unsigned</TD><TD>The width of the page image
3763  in pixels</TD></TR>
3764 <TR><TD>cupsHeight</TD><TD>unsigned</TD><TD>The height of the page image
3765  in pixels</TD></TR>
3766 <TR><TD>cupsMediaType</TD><TD>unsigned</TD><TD>The device-specific media
3767  type code</TD></TR>
3768 <TR><TD>cupsBitsPerColor</TD><TD>unsigned</TD><TD>The number of bits per
3769  color</TD></TR>
3770 <TR><TD>cupsBitsPerPixel</TD><TD>unsigned</TD><TD>The number of bits per
3771  pixel</TD></TR>
3772 <TR><TD>cupsBytesPerLine</TD><TD>unsigned</TD><TD>The number of bytes
3773  per line of image data</TD></TR>
3774 <TR><TD>cupsColorOrder</TD><TD>cups_order_t</TD><TD>The order of color
3775  values</TD></TR>
3776 <TR><TD>cupsColorSpace</TD><TD>cups_cspace_t</TD><TD>The type of color
3777  values</TD></TR>
3778 <TR><TD>cupsCompression</TD><TD>unsigned</TD><TD>The device-specific
3779  compression code</TD></TR>
3780 <TR><TD>cupsRowCount</TD><TD>unsigned</TD><TD>The device-specific row
3781  count</TD></TR>
3782 <TR><TD>cupsRowFeed</TD><TD>unsigned</TD><TD>The device-specific row
3783  feed</TD></TR>
3784 <TR><TD>cupsRowStep</TD><TD>unsigned</TD><TD>The device-specific row
3785  step</TD></TR>
3786 </TABLE>
3787 </CENTER>
3788 </P>
3789 <H1 ALIGN="RIGHT"><A HREF="FUNCTIONS" NAME="10">D - Functions</A></H1>
3790 <P>This appendix provides a reference for all of the CUPS API functions.
3791 <!-- NEW PAGE -->
3792 </P>
3793 <H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
3794 <H3><A NAME="10_1_1">Usage</A></H3>
3795 <PRE>
3796 int
3797 cupsAddOption(const char *name,
3798               const char *value,
3799               int num_options,
3800               cups_option_t **options);
3801 </PRE>
3802 <H3><A NAME="10_1_2">Arguments</A></H3>
3803 <CENTER>
3804 <TABLE BORDER WIDTH="80%">
3805 <TR><TH>Argument</TH><TH>Description</TH></TR>
3806 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
3807 <TR><TD>value</TD><TD>The value of the option.</TD></TR>
3808 <TR><TD>num_options</TD><TD>Number of options currently in the array.</TD>
3809 </TR>
3810 <TR><TD>options</TD><TD>Pointer to the options array.</TD></TR>
3811 </TABLE>
3812 </CENTER>
3813 <H3><A NAME="10_1_3">Returns</A></H3>
3814 <P>The new number of options.</P>
3815 <H3><A NAME="10_1_4">Description</A></H3>
3816 <P><CODE>cupsAddOption()</CODE> adds an option to the specified array.</P>
3817 <H3><A NAME="10_1_5">Example</A></H3>
3818 <PRE>
3819 #include &lt;cups.h&gt;
3820
3821 ...
3822
3823 /* Declare the options array */
3824 int           num_options;
3825 <A HREF="#cups_option_t">cups_option_t</A> *options;
3826
3827 /* Initialize the options array */
3828 num_options = 0;
3829 options     = (cups_option_t *)0;
3830
3831 /* Add options using cupsAddOption() */
3832 num_options = cupsAddOption(&quot;media&quot;, &quot;letter&quot;, num_options, &amp;options);
3833 num_options = cupsAddOption(&quot;resolution&quot;, &quot;300dpi&quot;, num_options, &amp;options);
3834 </PRE>
3835 <H3><A NAME="10_1_6">See Also</A></H3>
3836 <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>,<A HREF="#cupsGetOption">
3837  <CODE>cupsGetOption()</CODE></A>,<A HREF="#cupsParseOptions"> <CODE>
3838 cupsParseOptions()</CODE></A>
3839 <!-- NEW PAGE -->
3840
3841 <H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
3842 <H3><A NAME="10_2_1">Usage</A></H3>
3843 <PRE>
3844 int
3845 cupsCancelJob(const char *dest,
3846               int job);
3847 </PRE>
3848 <H3><A NAME="10_2_2">Arguments</A></H3>
3849 <CENTER>
3850 <TABLE BORDER WIDTH="80%">
3851 <TR><TH>Argument</TH><TH>Description</TH></TR>
3852 <TR><TD>dest</TD><TD>Printer or class name</TD></TR>
3853 <TR><TD>job</TD><TD>Job ID</TD></TR>
3854 </TABLE>
3855 </CENTER>
3856 <H3><A NAME="10_2_3">Returns</A></H3>
3857 <P>1 on success, 0 on failure. On failure the error can be found by
3858  calling<A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>.</P>
3859 <H3><A NAME="10_2_4">Description</A></H3>
3860 <P><CODE>cupsCancelJob()</CODE> cancels the specifies job.</P>
3861 <H3><A NAME="10_2_5">Example</A></H3>
3862 <PRE>
3863 #include &lt;cups.h&gt;
3864
3865 cupsCancelJob(&quot;LaserJet&quot;, 1);
3866 </PRE>
3867 <H3><A NAME="10_2_6">See Also</A></H3>
3868 <P><A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>,<A HREF="#cupsPrintFile">
3869  <CODE>cupsPrintFile()</CODE></A>
3870 <!-- NEW PAGE -->
3871 </P>
3872 <H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
3873 <H3><A NAME="10_3_1">Usage</A></H3>
3874 <PRE>
3875 ipp_t *
3876 cupsDoFileRequest(http_t *http,
3877                   ipp_t *request,
3878                   const char *resource,
3879                   const char *filename);
3880 </PRE>
3881 <H3><A NAME="10_3_2">Arguments</A></H3>
3882 <CENTER>
3883 <TABLE BORDER WIDTH="80%">
3884 <TR><TH>Argument</TH><TH>Description</TH></TR>
3885 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
3886 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
3887 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
3888 <TR><TD>filename</TD><TD>File to send with POST request (<CODE>NULL</CODE>
3889  pointer if none.)</TD></TR>
3890 </TABLE>
3891 </CENTER>
3892 <H3><A NAME="10_3_3">Returns</A></H3>
3893 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
3894  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
3895 cupsLastError()</CODE></A>.</P>
3896 <H3><A NAME="10_3_4">Description</A></H3>
3897 <P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and
3898  provides the IPP request and optionally the contents of a file to the
3899  IPP server. It also handles resubmitting the request and performing
3900  password authentication as needed.</P>
3901 <H3><A NAME="10_3_5">Example</A></H3>
3902 <PRE>
3903 #include &lt;cups.h&gt;
3904
3905 <A HREF="#http_t">http_t</A>      *http;
3906 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3907 <A HREF="#ipp_t">ipp_t</A>       *request;
3908 ipp_t       *response;
3909
3910 ...
3911
3912 /* Get the default language */
3913 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3914
3915 /* Create a new IPP request */
3916 request  = <A HREF="#ippNew">ippNew()</A>;
3917
3918 request-&gt;request.op.operation_id = IPP_PRINT_FILE;
3919 request-&gt;request.op.request_id   = 1;
3920
3921 /* Add required attributes */
3922 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3923              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3924
3925 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3926              &quot;attributes-natural-language&quot;, NULL,
3927              language != NULL ? language-&gt;language : &quot;C&quot;);
3928
3929 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
3930              NULL, &quot;ipp://hostname/resource&quot;);
3931
3932 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;requesting-user-name&quot;,
3933              NULL, <A HREF="#cupsUser">cupsUser()</A>);
3934
3935 /* Do the request... */
3936 response = cupsDoFileRequest(http, request, &quot;/resource&quot;, &quot;filename.txt&quot;);
3937 </PRE>
3938 <H3><A NAME="10_3_6">See Also</A></H3>
3939 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
3940  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
3941 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
3942 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
3943  <CODE>ippNew()</CODE></A>
3944 <!-- NEW PAGE -->
3945 </P>
3946 <H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
3947 <H3><A NAME="10_4_1">Usage</A></H3>
3948 <PRE>
3949 ipp_t *
3950 cupsDoRequest(http_t *http,
3951               ipp_t *request,
3952               const char *resource);
3953 </PRE>
3954 <H3><A NAME="10_4_2">Arguments</A></H3>
3955 <CENTER>
3956 <TABLE BORDER WIDTH="80%">
3957 <TR><TH>Argument</TH><TH>Description</TH></TR>
3958 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
3959 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
3960 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
3961 </TABLE>
3962 </CENTER>
3963 <H3><A NAME="10_4_3">Returns</A></H3>
3964 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
3965  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
3966 cupsLastError()</CODE></A>.</P>
3967 <H3><A NAME="10_4_4">Description</A></H3>
3968 <P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
3969  the IPP request to the IPP server. It also handles resubmitting the
3970  request and performing password authentication as needed.</P>
3971 <H3><A NAME="10_4_5">Example</A></H3>
3972 <PRE>
3973 #include &lt;cups.h&gt;
3974
3975 <A HREF="#http_t">http_t</A>      *http;
3976 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3977 <A HREF="#ipp_t">ipp_t</A>       *request;
3978 ipp_t       *response;
3979
3980 ...
3981
3982 /* Get the default language */
3983 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3984
3985 /* Create a new IPP request */
3986 request  = <A HREF="#ippNew">ippNew()</A>;
3987
3988 request-&gt;request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
3989 request-&gt;request.op.request_id   = 1;
3990
3991 /* Add required attributes */
3992 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3993              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3994
3995 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3996              &quot;attributes-natural-language&quot;, NULL,
3997              language != NULL ? language-&gt;language : &quot;C&quot;);
3998
3999 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
4000              NULL, &quot;ipp://hostname/resource&quot;);
4001
4002 /* Do the request... */
4003 response = cupsDoRequest(http, request, &quot;/resource&quot;);
4004 </PRE>
4005 <H3><A NAME="10_4_6">See Also</A></H3>
4006 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
4007  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
4008 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
4009 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
4010  <CODE>ippNew()</CODE></A>
4011 <!-- NEW PAGE -->
4012 </P>
4013 <H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
4014 <H3><A NAME="10_5_1">Usage</A></H3>
4015 <PRE>
4016 void
4017 cupsFreeOptions(int num_options,
4018                 cups_option_t *options);
4019
4020 </PRE>
4021 <H3><A NAME="10_5_2">Arguments</A></H3>
4022 <CENTER>
4023 <TABLE BORDER WIDTH="80%">
4024 <TR><TH>Argument</TH><TH>Description</TH></TR>
4025 <TR><TD>num_options</TD><TD>Number of options in array.</TD></TR>
4026 <TR><TD>options</TD><TD>Pointer to options array.</TD></TR>
4027 </TABLE>
4028 </CENTER>
4029 <H3><A NAME="10_5_3">Description</A></H3>
4030 <P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
4031  option array specified.</P>
4032 <H3><A NAME="10_5_4">Example</A></H3>
4033 <PRE>
4034 #include &lt;cups/cups.h&gt;
4035
4036 int           num_options;
4037 cups_option_t *options;
4038
4039 ...
4040
4041 cupsFreeOptions(num_options, options);
4042 </PRE>
4043 <H3><A NAME="10_5_5">See Also</A></H3>
4044 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsGetOption">
4045  cupsGetOption()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>,<A
4046 HREF="#cupsParseOptions"> cupsParseOptions()</A>
4047 <!-- NEW PAGE -->
4048 </P>
4049 <H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
4050 <H3><A NAME="10_6_1">Usage</A></H3>
4051 <PRE>
4052 int
4053 cupsGetClasses(char ***classes);
4054 </PRE>
4055 <H3><A NAME="10_6_2">Arguments</A></H3>
4056 <CENTER>
4057 <TABLE BORDER WIDTH="80%">
4058 <TR><TH>Argument</TH><TH>Description</TH></TR>
4059 <TR><TD>classes</TD><TD>Pointer to character pointer array.</TD></TR>
4060 </TABLE>
4061 </CENTER>
4062 <H3><A NAME="10_6_3">Returns</A></H3>
4063 <P>The number of printer classes available.</P>
4064 <H3><A NAME="10_6_4">Description</A></H3>
4065 <P><CODE>cupsGetClasses()</CODE> gets a list of the available printer
4066  classes. The returned array should be freed using the <CODE>free()</CODE>
4067  when it is no longer needed.</P>
4068 <H3><A NAME="10_6_5">Example</A></H3>
4069 <PRE>
4070 #include &lt;cups/cups.h&gt;
4071
4072 int  i;
4073 int  num_classes;
4074 char **classes;
4075
4076 ...
4077
4078 num_classes = cupsGetClasses(
4079
4080 ...
4081
4082 if (num_classes &gt; 0)
4083 {
4084   for (i = 0; i &lt;num_classes; i ++)
4085     free(classes[i]);
4086
4087   free(classes);
4088 }
4089 </PRE>
4090 <H3><A NAME="10_6_6">See Also</A></H3>
4091 <P><A HREF="#cupsGetDefault"> cupsGetDefault(),<A HREF="#cupsGetPrinters">
4092  cupsGetPrinters()
4093 <!-- NEW PAGE -->
4094 </A></A></P>
4095 <H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
4096 <H3><A NAME="10_7_1">Usage</A></H3>
4097 <PRE>
4098 const char *
4099 cupsGetDefault(void);
4100 </PRE>
4101 <H3><A NAME="10_7_2">Returns</A></H3>
4102 <P>A pointer to the default destination.</P>
4103 <H3><A NAME="10_7_3">Description</A></H3>
4104 <P><CODE>cupsGetDefault()</CODE> gets the default destination printer or
4105  class. The default destination is stored in a static string and will be
4106  overwritten (usually with the same value) after each call.</P>
4107 <H3><A NAME="10_7_4">Example</A></H3>
4108 <PRE>
4109 #include &lt;cups/cups.h&gt;
4110
4111 printf(&quot;The default destination is %s\n&quot;, cupsGetDefault());
4112 </PRE>
4113 <H3><A NAME="10_7_5">See Also</A></H3>
4114 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetPrinters">
4115  cupsGetPrinters()
4116 <!-- NEW PAGE -->
4117 </A></A></P>
4118 <H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
4119 <H3><A NAME="10_8_1">Usage</A></H3>
4120 <PRE>
4121 const char *
4122 cupsGetOption(const char *name,
4123               int num_options,
4124               cups_option_t *options);
4125 </PRE>
4126 <H3><A NAME="10_8_2">Arguments</A></H3>
4127 <CENTER>
4128 <TABLE BORDER WIDTH="80%">
4129 <TR><TH>Argument</TH><TH>Description</TH></TR>
4130 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
4131 <TR><TD>num_options</TD><TD>The number of options in the array.</TD></TR>
4132 <TR><TD>options</TD><TD>The options array.</TD></TR>
4133 </TABLE>
4134 </CENTER>
4135 <H3><A NAME="10_8_3">Returns</A></H3>
4136 <P>A pointer to the option values or <CODE>NULL</CODE> if the option is
4137  not defined.</P>
4138 <H3><A NAME="10_8_4">Description</A></H3>
4139 <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
4140  named option. If the option is not included in the options array then a
4141  <CODE>NULL</CODE> pointer is returned.</P>
4142 <PRE>
4143 #include &lt;cups/cups.h&gt;
4144
4145 int           num_options;
4146 cups_option_t *options;
4147 const char    *media;
4148
4149 ...
4150
4151 media = cupsGetOption(&quot;media&quot;, num_options, options);
4152 </PRE>
4153 <H3><A NAME="10_8_5">See Also</A></H3>
4154 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4155  cupsFreeOptions()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>
4156 ,<A HREF="#cupsParseOptions"> cupsParseOptions()</A>
4157 <!-- NEW PAGE -->
4158 </P>
4159 <H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
4160 <H3><A NAME="10_9_1">Usage</A></H3>
4161 <PRE>
4162 const char *
4163 cupsGetPassword(const char *prompt);
4164 </PRE>
4165 <H3><A NAME="10_9_2">Arguments</A></H3>
4166 <CENTER>
4167 <TABLE BORDER WIDTH="80%">
4168 <TR><TH>Argument</TH><TH>Description</TH></TR>
4169 <TR><TD>prompt</TD><TD>The prompt to display to the user.</TD></TR>
4170 </TABLE>
4171 </CENTER>
4172 <H3><A NAME="10_9_3">Returns</A></H3>
4173 <P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
4174  password was entered.</P>
4175 <H3><A NAME="10_9_4">Description</A></H3>
4176 <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks
4177  the user for a password. The password text is not echoed to the user.</P>
4178 <H3><A NAME="10_9_5">Example</A></H3>
4179 <PRE>
4180 #include &lt;cups/cups.h&gt;
4181
4182 char *password;
4183
4184 ...
4185
4186 password = cupsGetPassword(&quot;Please enter a password:&quot;);
4187 </PRE>
4188 <H3><A NAME="10_9_6">See Also</A></H3>
4189 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
4190  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
4191 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()"> cupsUser()</A>
4192 <!-- NEW PAGE -->
4193
4194 </P>
4195 <H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
4196 <H3><A NAME="10_10_1">Usage</A></H3>
4197 <PRE>
4198 const char *
4199 cupsGetPPD(const char *printer);
4200 </PRE>
4201 <H3><A NAME="10_10_2">Arguments</A></H3>
4202 <CENTER>
4203 <TABLE BORDER WIDTH="80%">
4204 <TR><TH>Argument</TH><TH>Description</TH></TR>
4205 <TR><TD>printer</TD><TD>The name of the printer.</TD></TR>
4206 </TABLE>
4207 </CENTER>
4208 <H3><A NAME="10_10_3">Returns</A></H3>
4209 <P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
4210  if the printer cannot be located or does not have a PPD file.</P>
4211 <H3><A NAME="10_10_4">Description</A></H3>
4212 <P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named
4213  printer. The printer name can be of the form &quot;printer&quot; or
4214  &quot;printer@hostname&quot;.</P>
4215 <P>You should remove (unlink) the PPD file after you are done using it.
4216  The filename is stored in a static buffer and will be overwritten with
4217  each call to <CODE>cupsGetPPD()</CODE>.</P>
4218 <H3><A NAME="10_10_5">Example</A></H3>
4219 <PRE>
4220 #include &lt;cups/cups.h&gt;
4221
4222 char *ppd;
4223
4224 ...
4225
4226 ppd = cupsGetPPD(&quot;printer@hostname&quot;);
4227
4228 ...
4229
4230 unlink(ppd);
4231 </PRE>
4232
4233 <!-- NEW PAGE -->
4234 <H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
4235 <H3><A NAME="10_11_1">Usage</A></H3>
4236 <PRE>
4237 int
4238 cupsGetPrinters(char ***printers);
4239 </PRE>
4240 <H3><A NAME="10_11_2">Arguments</A></H3>
4241 <CENTER>
4242 <TABLE BORDER WIDTH="80%">
4243 <TR><TH>Argument</TH><TH>Description</TH></TR>
4244 <TR><TD>printers</TD><TD>Pointer to character pointer array.</TD></TR>
4245 </TABLE>
4246 </CENTER>
4247 <H3><A NAME="10_11_3">Returns</A></H3>
4248 <P>The number of printer printers available.</P>
4249 <H3><A NAME="10_11_4">Description</A></H3>
4250 <P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
4251  The returned array should be freed using the <CODE>free()</CODE> when
4252  it is no longer needed.</P>
4253 <H3><A NAME="10_11_5">Example</A></H3>
4254 <PRE>
4255 #include &lt;cups/cups.h&gt;
4256
4257 int  i;
4258 int  num_printers;
4259 char **printers;
4260
4261 ...
4262
4263 num_printers = cupsGetPrinters(
4264
4265 ...
4266
4267 if (num_printers &gt; 0)
4268 {
4269   for (i = 0; i &lt;num_printers; i ++)
4270     free(printers[i]);
4271
4272   free(printers);
4273 }
4274 </PRE>
4275 <H3><A NAME="10_11_6">See Also</A></H3>
4276 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetDefault">
4277  cupsGetDefault()
4278 <!-- NEW PAGE -->
4279 </A></A></P>
4280 <H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
4281 <H3><A NAME="10_12_1">Usage</A></H3>
4282 <PRE>
4283 const char *
4284 cupsLangDefault(void);
4285 </PRE>
4286 <H3><A NAME="10_12_2">Returns</A></H3>
4287 <P>A pointer to the default language structure.</P>
4288 <H3><A NAME="10_12_3">Description</A></H3>
4289 <P><CODE>cupsLangDefault()</CODE> returns a language structure for the
4290  default language. The default language is defined by the <CODE>LANG</CODE>
4291  environment variable. If the specified language cannot be located then
4292  the POSIX (English) locale is used.</P>
4293 <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with
4294  the language structure when you are done.</P>
4295 <H3><A NAME="10_12_4">Example</A></H3>
4296 <PRE>
4297 #include &lt;cups/language.h&gt;
4298
4299 cups_lang_t *language;
4300 ...
4301
4302 language = cupsLangDefault();
4303
4304 ...
4305
4306 cupsLangFree(language);
4307 </PRE>
4308 <H3><A NAME="10_12_5">See Also</A></H3>
4309 <P><A HREF="#cupsLangEncoding"> cupsLangEncoding()</A>,<A HREF="#cupsLangFlush">
4310  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4311  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4312 <!-- NEW PAGE -->
4313 </P>
4314 <H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
4315 <H3><A NAME="10_13_1">Usage</A></H3>
4316 <PRE>
4317 char *
4318 cupsLangEncoding(cups_lang_t *language);
4319 </PRE>
4320 <H3><A NAME="10_13_2">Arguments</A></H3>
4321 <CENTER>
4322 <TABLE BORDER WIDTH="80%">
4323 <TR><TH>Argument</TH><TH>Description</TH></TR>
4324 <TR><TD>language</TD><TD>The language structure.</TD></TR>
4325 </TABLE>
4326 </CENTER>
4327 <H3><A NAME="10_13_3">Returns</A></H3>
4328 <P>A pointer to the encoding string.</P>
4329 <H3><A NAME="10_13_4">Description</A></H3>
4330 <P><CODE>cupsLangEncoding()</CODE> returns the language encoding used
4331  for the specified language, e.g. &quot;iso-8859-1&quot;, &quot;utf-8&quot;, etc.</P>
4332 <H3><A NAME="10_13_5">Example</A></H3>
4333 <PRE>
4334 #include &lt;cups/language.h&gt;
4335
4336 cups_lang_t *language;
4337 char        *encoding;
4338 ...
4339
4340 language = cupsLangDefault();
4341 encoding = cupsLangEncoding(language);
4342 ...
4343
4344 cupsLangFree(language);
4345 </PRE>
4346 <H3><A NAME="10_13_6">See Also</A></H3>
4347 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangFlush">
4348  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4349  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4350 <!-- NEW PAGE -->
4351 </P>
4352 <H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
4353 <H3><A NAME="10_14_1">Usage</A></H3>
4354 <PRE>
4355 void
4356 cupsLangFlush(void);
4357 </PRE>
4358 <H3><A NAME="10_14_2">Description</A></H3>
4359 <P><CODE>cupsLangFlush()</CODE> frees all language structures that have
4360  been allocated.</P>
4361 <H3><A NAME="10_14_3">Example</A></H3>
4362 <PRE>
4363 #include &lt;cups/language.h&gt;
4364
4365 ...
4366
4367 cupsLangFlush();
4368 </PRE>
4369 <H3><A NAME="10_14_4">See Also</A></H3>
4370 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4371  cupsLangEncoding()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4372  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4373 <!-- NEW PAGE -->
4374 </P>
4375 <H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
4376 <H3><A NAME="10_15_1">Usage</A></H3>
4377 <PRE>
4378 void
4379 cupsLangFree(cups_lang_t *language);
4380 </PRE>
4381 <H3><A NAME="10_15_2">Arguments</A></H3>
4382 <CENTER>
4383 <TABLE BORDER WIDTH="80%">
4384 <TR><TH>Argument</TH><TH>Description</TH></TR>
4385 <TR><TD>language</TD><TD>The language structure to free.</TD></TR>
4386 </TABLE>
4387 </CENTER>
4388 <H3><A NAME="10_15_3">Description</A></H3>
4389 <P><CODE>cupsLangFree()</CODE> frees the specified language structure.</P>
4390 <H3><A NAME="10_15_4">Example</A></H3>
4391 <PRE>
4392 #include &lt;cups/language.h&gt;
4393
4394 cups_lang_t *language;
4395 ...
4396
4397 cupsLangFree(language);
4398 </PRE>
4399 <H3><A NAME="10_15_5">See Also</A></H3>
4400 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4401  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangGet">
4402  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4403 <!-- NEW PAGE -->
4404 </P>
4405 <H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
4406 <H3><A NAME="10_16_1">Usage</A></H3>
4407 <PRE>
4408 cups_lang_t *
4409 cupsLangGet(const char *name);
4410 </PRE>
4411 <H3><A NAME="10_16_2">Arguments</A></H3>
4412 <CENTER>
4413 <TABLE BORDER WIDTH="80%">
4414 <TR><TH>Argument</TH><TH>Description</TH></TR>
4415 <TR><TD>name</TD><TD>The name of the locale.</TD></TR>
4416 </TABLE>
4417 </CENTER>
4418 <H3><A NAME="10_16_3">Returns</A></H3>
4419 <P>A pointer to a language structure.</P>
4420 <H3><A NAME="10_16_4">Description</A></H3>
4421 <P><CODE>cupsLangGet()</CODE> returns a language structure for the
4422  specified locale. If the locale is not defined then the POSIX (English)
4423  locale is substituted.</P>
4424 <H3><A NAME="10_16_5">Example</A></H3>
4425 <PRE>
4426 #include &lt;cups/language.h&gt;
4427
4428 cups_lang_t *language;
4429
4430 ...
4431
4432 language = cupsLangGet(&quot;fr&quot;);
4433
4434 ...
4435
4436 cupsLangFree(language);
4437 </PRE>
4438 <H3><A NAME="10_16_6">See Also</A></H3>
4439 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4440  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4441  cupsLangFree()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4442 <!-- NEW PAGE -->
4443 </P>
4444 <H2><A NAME="cupsLangString">cupsLangString()</A></H2>
4445 <H3><A NAME="10_17_1">Usage</A></H3>
4446 <PRE>
4447 char *
4448 cupsLangString(cups_lang_t *language,
4449                int         message);
4450 </PRE>
4451 <H3><A NAME="10_17_2">Arguments</A></H3>
4452 <CENTER>
4453 <TABLE BORDER WIDTH="80%">
4454 <TR><TH>Argument</TH><TH>Description</TH></TR>
4455 <TR><TD>language</TD><TD>The language to query.</TD></TR>
4456 <TR><TD>message</TD><TD>The message number.</TD></TR>
4457 </TABLE>
4458 </CENTER>
4459 <H3><A NAME="10_17_3">Returns</A></H3>
4460 <P>A pointer to the message string or <CODE>NULL</CODE> if the message
4461  is not defined.</P>
4462 <H3><A NAME="10_17_4">Description</A></H3>
4463 <P><CODE>cupsLangString()</CODE> returns a pointer to the specified
4464  message string in the specified language.</P>
4465 <H3><A NAME="10_17_5">Example</A></H3>
4466 <PRE>
4467 #include &lt;cups/language.h&gt;
4468
4469 cups_lang_t *language;
4470 char        *s;
4471 ...
4472
4473 language = cupsLangGet(&quot;fr&quot;);
4474
4475 s = cupsLangString(language, CUPS_MSG_YES);
4476
4477 ...
4478
4479 cupsLangFree(language);
4480 </PRE>
4481 <H3><A NAME="10_17_6">See Also</A></H3>
4482 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4483  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4484  cupsLangFree()</A>,<A HREF="#cupsLangGet"> cupsLangGet()</A>
4485 <!-- NEW PAGE -->
4486 </P>
4487 <H2><A NAME="cupsLastError">cupsLastError()</A></H2>
4488 <H3><A NAME="10_18_1">Usage</A></H3>
4489 <PRE>
4490 ipp_status_t
4491 cupsLastError(void);
4492 </PRE>
4493 <H3><A NAME="10_18_2">Returns</A></H3>
4494 <P>An enumeration containing the last IPP error.</P>
4495 <H3><A NAME="10_18_3">Description</A></H3>
4496 <P><CODE>cupsLastError()</CODE> returns the last IPP error that
4497  occurred. If no error occurred then it will return <CODE>IPP_OK</CODE>
4498  or <CODE>IPP_OK_CONFLICT</CODE>.</P>
4499 <H3><A NAME="10_18_4">Example</A></H3>
4500 <PRE>
4501 #include &lt;cups/cups.h&gt;
4502
4503 ipp_status_t status;
4504
4505 ...
4506
4507 status = cupsLastError();
4508 </PRE>
4509 <H3><A NAME="10_18_5">See Also</A></H3>
4510 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsPrintFile">
4511  cupsPrintFile()</A>
4512 <!-- NEW PAGE -->
4513 </P>
4514 <H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
4515 <H3><A NAME="10_19_1">Usage</A></H3>
4516 <PRE>
4517 int
4518 cupsMarkOptions(ppd_file_t *ppd,
4519                 int num_options,
4520                 cups_option_t *options);
4521 </PRE>
4522 <H3><A NAME="10_19_2">Arguments</A></H3>
4523 <CENTER>
4524 <TABLE BORDER WIDTH="80%">
4525 <TR><TH>Argument</TH><TH>Description</TH></TR>
4526 <TR><TD>ppd</TD><TD>The PPD file to mark.</TD></TR>
4527 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4528 </TR>
4529 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4530 </TABLE>
4531 </CENTER>
4532 <H3><A NAME="10_19_3">Returns</A></H3>
4533 <P>The number of conflicts found.</P>
4534 <H3><A NAME="10_19_4">Description</A></H3>
4535 <P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
4536  handles mapping of IPP option names and values to PPD option names.</P>
4537 <H3><A NAME="10_19_5">Example</A></H3>
4538 <PRE>
4539 #include &lt;cups/cups.h&gt;
4540
4541 int           num_options;
4542 cups_option_t *options;
4543 ppd_file_t    *ppd;
4544
4545 ...
4546
4547 cupsMarkOptions(ppd, num_options, options);
4548 </PRE>
4549 <H3><A NAME="10_19_6">See Also</A></H3>
4550 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4551  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsParseOptions">
4552  cupsParseOptions()</A>
4553 <!-- NEW PAGE -->
4554 </P>
4555 <H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
4556 <H3><A NAME="10_20_1">Usage</A></H3>
4557 <PRE>
4558 int
4559 cupsParseOptions(const char *arg,
4560                  int num_options,
4561                  cups_option_t **options);
4562 </PRE>
4563 <H3><A NAME="10_20_2">Arguments</A></H3>
4564 <CENTER>
4565 <TABLE BORDER WIDTH="80%">
4566 <TR><TH>Argument</TH><TH>Description</TH></TR>
4567 <TR><TD>arg</TD><TD>The string containing one or more options.</TD></TR>
4568 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4569 </TR>
4570 <TR><TD>options</TD><TD>A pointer to the options array pointer.</TD></TR>
4571 </TABLE>
4572 </CENTER>
4573 <H3><A NAME="10_20_3">Returns</A></H3>
4574 <P>The new number of options in the array.</P>
4575 <H3><A NAME="10_20_4">Description</A></H3>
4576 <P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
4577  or more options of the form &quot;name=value&quot;, &quot;name&quot;, or &quot;noname&quot;. It can
4578  be called multiple times to combine the options from several strings.</P>
4579 <H3><A NAME="10_20_5">Example</A></H3>
4580 <PRE>
4581 #include &lt;cups/cups.h&gt;
4582
4583 int           num_options;
4584 cups_option_t *options;
4585
4586 ...
4587
4588 num_options = 0;
4589 options     = (cups_option_t *)0;
4590 num_options = cupsParseOptions(argv[5], num_options, &amp;options);
4591 </PRE>
4592 <H3><A NAME="10_20_6">See Also</A></H3>
4593 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4594  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsMarkOptions">
4595  cupsMarkOptions()</A>
4596 <!-- NEW PAGE -->
4597 </P>
4598 <H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
4599 <H3><A NAME="10_21_1">Usage</A></H3>
4600 <PRE>
4601 int
4602 cupsPrintFile(const char    *printer,
4603               const char    *filename,
4604               const char    *title,
4605               int           num_options,
4606               cups_option_t *options);
4607 </PRE>
4608 <H3><A NAME="10_21_2">Arguments</A></H3>
4609 <CENTER>
4610 <TABLE BORDER WIDTH="80%">
4611 <TR><TH>Argument</TH><TH>Description</TH></TR>
4612 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4613 <TR><TD>filename</TD><TD>The file to print.</TD></TR>
4614 <TR><TD>title</TD><TD>The job title.</TD></TR>
4615 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4616 </TR>
4617 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4618 </TABLE>
4619 </CENTER>
4620 <H3><A NAME="10_21_3">Returns</A></H3>
4621 <P>The new job ID number or 0 on error.</P>
4622 <H3><A NAME="10_21_4">Description</A></H3>
4623 <P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
4624  class for printing. If the job cannot be printed the error code can be
4625  found by calling <CODE>cupsLastError()</CODE>.</P>
4626 <H3><A NAME="10_21_5">Example</A></H3>
4627 <PRE>
4628 #include &lt;cups/cups.h&gt;
4629
4630 int           num_options;
4631 cups_option_t *options;
4632 int           jobid;
4633
4634 ...
4635
4636 jobid = cupsPrintFile(&quot;printer@hostname&quot;, &quot;filename.ps&quot;, &quot;Job Title&quot;,
4637                       num_options, options);
4638 </PRE>
4639 <H3><A NAME="10_21_6">See Also</A></H3>
4640 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4641  cupsLastError()</A>,<A HREF="#cupsPrintFiles"> cupsPrintFiles()</A>
4642 <!-- NEW PAGE -->
4643 </P>
4644 <H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
4645 <H3><A NAME="10_22_1">Usage</A></H3>
4646 <PRE>
4647 int
4648 cupsPrintFiles(const char    *printer,
4649                int           num_files,
4650                const char    **files,
4651                const char    *title,
4652                int           num_options,
4653                cups_option_t *options);
4654 </PRE>
4655 <H3><A NAME="10_22_2">Arguments</A></H3>
4656 <CENTER>
4657 <TABLE BORDER WIDTH="80%">
4658 <TR><TH>Argument</TH><TH>Description</TH></TR>
4659 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4660 <TR><TD>num_files</TD><TD>The number of files to print.</TD></TR>
4661 <TR><TD>files</TD><TD>The files to print.</TD></TR>
4662 <TR><TD>title</TD><TD>The job title.</TD></TR>
4663 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4664 </TR>
4665 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4666 </TABLE>
4667 </CENTER>
4668 <H3><A NAME="10_22_3">Returns</A></H3>
4669 <P>The new job ID number or 0 on error.</P>
4670 <H3><A NAME="10_22_4">Description</A></H3>
4671 <P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4672  printer or class for printing. If the job cannot be printed the error
4673  code can be found by calling <CODE>cupsLastError()</CODE>.</P>
4674 <H3><A NAME="10_22_5">Example</A></H3>
4675 <PRE>
4676 #include &lt;cups/cups.h&gt;
4677
4678 int           num_files;
4679 const char    *files[100];
4680 int           num_options;
4681 cups_option_t *options;
4682 int           jobid;
4683
4684 ...
4685
4686 jobid = cupsPrintFiles(&quot;printer@hostname&quot;, num_files, files,
4687                        &quot;Job Title&quot;, num_options, options);
4688 </PRE>
4689 <H3><A NAME="10_22_6">See Also</A></H3>
4690 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4691  cupsLastError()</A>,<A HREF="#cupsPrintFile"> cupsPrintFile()</A>
4692 <!-- NEW PAGE -->
4693 </P>
4694 <H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
4695 <H3><A NAME="10_23_1">Usage</A></H3>
4696 <PRE>
4697 void
4698 cupsRasterClose(cups_raster_t *ras);
4699 </PRE>
4700 <H3><A NAME="10_23_2">Arguments</A></H3>
4701 <CENTER>
4702 <TABLE BORDER WIDTH="80%">
4703 <TR><TH>Argument</TH><TH>Description</TH></TR>
4704 <TR><TD>ras</TD><TD>The raster stream to close.</TD></TR>
4705 </TABLE>
4706 </CENTER>
4707 <H3><A NAME="10_23_3">Description</A></H3>
4708 <P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.</P>
4709 <H3><A NAME="10_23_4">Example</A></H3>
4710 <PRE>
4711 #include &lt;cups/raster.h&gt;
4712
4713 cups_raster_t *ras;
4714
4715 ...
4716
4717 cupsRasterClose(ras);
4718 </PRE>
4719 <H3><A NAME="10_23_5">See Also</A></H3>
4720 <P><A HREF="#cupsRasterOpen"> cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4721  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4722  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4723  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4724  cupsRasterWritePixels()</A>
4725 <!-- NEW PAGE -->
4726 </P>
4727 <H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
4728 <H3><A NAME="10_24_1">Usage</A></H3>
4729 <PRE>
4730 cups_raster_t *
4731 cupsRasterOpen(int fd,
4732                cups_mode_t mode);
4733 </PRE>
4734 <H3><A NAME="10_24_2">Arguments</A></H3>
4735 <CENTER>
4736 <TABLE BORDER WIDTH="80%">
4737 <TR><TH>Argument</TH><TH>Description</TH></TR>
4738 <TR><TD>fd</TD><TD>The file descriptor to use.</TD></TR>
4739 <TR><TD>mode</TD><TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or <CODE>
4740 CUPS_RASTER_WRITE</CODE>.</TD></TR>
4741 </TABLE>
4742 </CENTER>
4743 <H3><A NAME="10_24_3">Returns</A></H3>
4744 <P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an
4745  error.</P>
4746 <H3><A NAME="10_24_4">Description</A></H3>
4747 <P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or
4748  writing.</P>
4749 <H3><A NAME="10_24_5">Example</A></H3>
4750 <PRE>
4751 #include &lt;cups/raster.h&gt;
4752
4753 cups_raster_t *ras;
4754
4755 ...
4756
4757 ras = cupsRasterOpen(0, CUPS_RASTER_READ);
4758 </PRE>
4759 <H3><A NAME="10_24_6">See Also</A></H3>
4760 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterReadHeader">
4761  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4762  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4763  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4764  cupsRasterWritePixels()</A>
4765 <!-- NEW PAGE -->
4766 </P>
4767 <H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
4768 <H3><A NAME="10_25_1">Usage</A></H3>
4769 <PRE>
4770 unsigned
4771 cupsRasterReadHeader(cups_raster_t *ras,
4772                      cups_page_header_t *header);
4773 </PRE>
4774 <H3><A NAME="10_25_2">Arguments</A></H3>
4775 <CENTER>
4776 <TABLE BORDER WIDTH="80%">
4777 <TR><TH>Argument</TH><TH>Description</TH></TR>
4778 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
4779 <TR><TD>header</TD><TD>A pointer to a page header structure to read
4780  into.</TD></TR>
4781 </TABLE>
4782 </CENTER>
4783 <H3><A NAME="10_25_3">Returns</A></H3>
4784 <P>1 on success, 0 on EOF or error.</P>
4785 <H3><A NAME="10_25_4">Description</A></H3>
4786 <P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the
4787  specified raster stream.</P>
4788 <H3><A NAME="10_25_5">Example</A></H3>
4789 <PRE>
4790 #include &lt;cups/raster.h&gt;
4791
4792 int                  line;
4793 cups_raster_t        *ras;
4794 cups_raster_header_t header;
4795 unsigned char        pixels[8192];
4796 ...
4797
4798 while (cupsRasterReadHeader(ras, &amp;header))
4799 {
4800   ...
4801
4802   for (line = 0; line &lt; header.cupsHeight; line ++)
4803   {
4804     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4805
4806     ...
4807   }
4808 }
4809 </PRE>
4810 <H3><A NAME="10_25_6">See Also</A></H3>
4811 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4812  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadPixels">
4813  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4814  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4815  cupsRasterWritePixels()</A>
4816 <!-- NEW PAGE -->
4817 </P>
4818 <H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
4819 <H3><A NAME="10_26_1">Usage</A></H3>
4820 <PRE>
4821 unsigned
4822 cupsRasterReadPixels(cups_raster_t *ras,
4823                      unsigned char *pixels,
4824                      unsigned length);
4825 </PRE>
4826 <H3><A NAME="10_26_2">Arguments</A></H3>
4827 <CENTER>
4828 <TABLE BORDER WIDTH="80%">
4829 <TR><TH>Argument</TH><TH>Description</TH></TR>
4830 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
4831 <TR><TD>pixels</TD><TD>The pointer to a pixel buffer.</TD></TR>
4832 <TR><TD>length</TD><TD>The number of bytes of pixel data to read.</TD></TR>
4833 </TABLE>
4834 </CENTER>
4835 <H3><A NAME="10_26_3">Returns</A></H3>
4836 <P>The number of bytes read or 0 on EOF or error.</P>
4837 <H3><A NAME="10_26_4">Description</A></H3>
4838 <P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the
4839  specified raster stream.</P>
4840 <H3><A NAME="10_26_5">Example</A></H3>
4841 <PRE>
4842 #include &lt;cups/raster.h&gt;
4843
4844 int                  line;
4845 cups_raster_t        *ras;
4846 cups_raster_header_t header;
4847 unsigned char        pixels[8192];
4848 ...
4849
4850 while (cupsRasterReadHeader(ras, &amp;header))
4851 {
4852   ...
4853
4854   for (line = 0; line &lt; header.cupsHeight; line ++)
4855   {
4856     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4857
4858     ...
4859   }
4860 }
4861 </PRE>
4862 <H3><A NAME="10_26_6">See Also</A></H3>
4863 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4864  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4865  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterWriteHeader">
4866  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4867  cupsRasterWritePixels()</A>
4868 <!-- NEW PAGE -->
4869 </P>
4870 <H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
4871 <H3><A NAME="10_27_1">Usage</A></H3>
4872 <PRE>
4873 unsigned
4874 cupsRasterWriteHeader(cups_raster_t *ras,
4875                       cups_page_header_t *header);
4876 </PRE>
4877 <H3><A NAME="10_27_2">Arguments</A></H3>
4878 <CENTER>
4879 <TABLE BORDER WIDTH="80%">
4880 <TR><TH>Argument</TH><TH>Description</TH></TR>
4881 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
4882 <TR><TD>header</TD><TD>A pointer to the page header to write.</TD></TR>
4883 </TABLE>
4884 </CENTER>
4885 <H3><A NAME="10_27_3">Returns</A></H3>
4886 <P>1 on success, 0 on error.</P>
4887 <H3><A NAME="10_27_4">Description</A></H3>
4888 <P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header
4889  to a raster stream.</P>
4890 <H3><A NAME="10_27_5">Example</A></H3>
4891 <PRE>
4892 #include &lt;cups/raster.h&gt;
4893
4894 int                  line;
4895 cups_raster_t        *ras;
4896 cups_raster_header_t header;
4897 unsigned char        pixels[8192];
4898 ...
4899
4900 cupsRasterWriteHeader(ras, &amp;header);
4901
4902 for (line = 0; line &lt; header.cupsHeight; line ++)
4903 {
4904   ...
4905
4906   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4907 }
4908 </PRE>
4909 <H3><A NAME="10_27_6">See Also</A></H3>
4910 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4911  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4912  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4913  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWritePixels">
4914  cupsRasterWritePixels()</A>
4915 <!-- NEW PAGE -->
4916 </P>
4917 <H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
4918 <H3><A NAME="10_28_1">Usage</A></H3>
4919 <PRE>
4920 unsigned
4921 cupsRasterWritePixels(cups_raster_t *ras,
4922                       unsigned char *pixels,
4923                       unsigned length);
4924 </PRE>
4925 <H3><A NAME="10_28_2">Arguments</A></H3>
4926 <CENTER>
4927 <TABLE BORDER WIDTH="80%">
4928 <TR><TH>Argument</TH><TH>Description</TH></TR>
4929 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
4930 <TR><TD>pixels</TD><TD>The pixel data to write.</TD></TR>
4931 <TR><TD>length</TD><TD>The number of bytes to write.</TD></TR>
4932 </TABLE>
4933 </CENTER>
4934 <H3><A NAME="10_28_3">Returns</A></H3>
4935 <P>The number of bytes written.</P>
4936 <H3><A NAME="10_28_4">Description</A></H3>
4937 <P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data
4938  to a raster stream.</P>
4939 <H3><A NAME="10_28_5">Example</A></H3>
4940 <PRE>
4941 #include &lt;cups/raster.h&gt;
4942
4943 int                  line;
4944 cups_raster_t        *ras;
4945 cups_raster_header_t header;
4946 unsigned char        pixels[8192];
4947 ...
4948
4949 cupsRasterWriteHeader(ras, &amp;header);
4950
4951 for (line = 0; line &lt; header.cupsHeight; line ++)
4952 {
4953   ...
4954
4955   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4956 }
4957 </PRE>
4958 <H3><A NAME="10_28_6">See Also</A></H3>
4959 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4960  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4961  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4962  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4963  cupsRasterWriteHeader()</A>
4964 <!-- NEW PAGE -->
4965 </P>
4966 <H2><A NAME="cupsServer">cupsServer()</A></H2>
4967 <H3><A NAME="10_29_1">Usage</A></H3>
4968 <PRE>
4969 const char *
4970 cupsServer(void);
4971 </PRE>
4972 <H3><A NAME="10_29_2">Returns</A></H3>
4973 <P>A pointer to the default server name.</P>
4974 <H3><A NAME="10_29_3">Description</A></H3>
4975 <P><CODE>cupsServer()</CODE> returns a pointer to the default server
4976  name. The server name is stored in a static location and will be
4977  overwritten with every call to <CODE>cupsServer()</CODE></P>
4978 <P>The default server is determined from the following locations:</P>
4979 <OL>
4980 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,</LI>
4981 <LI>The <CODE>ServerName</CODE> directive in the<VAR> client.conf</VAR>
4982  file,</LI>
4983 <LI>The default host, &quot;localhost&quot;.</LI>
4984 </OL>
4985 <H3><A NAME="10_29_4">Example</A></H3>
4986 <PRE>
4987 #include &lt;cups/cups.h&gt;
4988
4989 const char *server;
4990
4991 server = cupsServer();
4992 </PRE>
4993 <H3><A NAME="10_29_5">See Also</A></H3>
4994 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsSetPasswordCB">
4995  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
4996 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser"> cupsUser()</A>
4997 <!-- NEW PAGE -->
4998
4999 </P>
5000 <H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
5001 <H3><A NAME="10_30_1">Usage</A></H3>
5002 <PRE>
5003 void
5004 cupsSetPasswordCB(const char *(*cb)(const char *prompt));
5005 </PRE>
5006 <H3><A NAME="10_30_2">Arguments</A></H3>
5007 <CENTER>
5008 <TABLE BORDER WIDTH="80%">
5009 <TR><TH>Argument</TH><TH>Description</TH></TR>
5010 <TR><TD>cb</TD><TD>The password callback function.</TD></TR>
5011 </TABLE>
5012 </CENTER>
5013 <H3><A NAME="10_30_3">Description</A></H3>
5014 <P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use
5015  when asking the user for a password. The callback function must accept
5016  a single character string pointer (the prompt string) and return <CODE>
5017 NULL</CODE> if the user did not enter a password string or a pointer to
5018  the password string otherwise.</P>
5019 <H3><A NAME="10_30_4">Example</A></H3>
5020 <PRE>
5021 #include &lt;cups/cups.h&gt;
5022
5023 const char *
5024 my_password_cb(const char *prompt)
5025 {
5026   return (getpass(prompt));
5027 }
5028
5029 ...
5030
5031 char *password;
5032
5033 ...
5034
5035 cupsSetPasswordCB(my_password_cb);
5036 password = cupsGetPassword(&quot;Please enter a password:&quot;);
5037 </PRE>
5038 <H3><A NAME="10_30_5">See Also</A></H3>
5039 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetServer">
5040  cupsSetServer()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()">
5041  cupsUser()</A>
5042 <!-- NEW PAGE -->
5043 </P>
5044 <H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
5045 <H3><A NAME="10_31_1">Usage</A></H3>
5046 <PRE>
5047 void
5048 cupsSetServer(const char *server);
5049 </PRE>
5050 <H3><A NAME="10_31_2">Arguments</A></H3>
5051 <CENTER>
5052 <TABLE BORDER WIDTH="80%">
5053 <TR><TH>Argument</TH><TH>Description</TH></TR>
5054 <TR><TD>server</TD><TD>The default server to use.</TD></TR>
5055 </TABLE>
5056 </CENTER>
5057 <H3><A NAME="10_31_3">Description</A></H3>
5058 <P><CODE>cupsSetServer()</CODE> sets the default server to use for the
5059  CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>, the
5060  default server is used.</P>
5061 <H3><A NAME="10_31_4">Example</A></H3>
5062 <PRE>
5063 #include &lt;cups/cups.h&gt;
5064
5065 cupsSetServer(&quot;foo.bar.com&quot;);
5066 </PRE>
5067 <H3><A NAME="10_31_5">See Also</A></H3>
5068 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5069  cupsSetPasswordCB()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()">
5070  cupsUser()</A>
5071 <!-- NEW PAGE -->
5072 </P>
5073 <H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
5074 <H3><A NAME="10_32_1">Usage</A></H3>
5075 <PRE>
5076 void
5077 cupsSetUser(const char *user);
5078 </PRE>
5079 <H3><A NAME="10_32_2">Arguments</A></H3>
5080 <CENTER>
5081 <TABLE BORDER WIDTH="80%">
5082 <TR><TH>Argument</TH><TH>Description</TH></TR>
5083 <TR><TD>user</TD><TD>The user name string to use.</TD></TR>
5084 </TABLE>
5085 </CENTER>
5086 <H3><A NAME="10_32_3">Description</A></H3>
5087 <P><CODE>cupsSetUser()</CODE> sets the default user name for
5088  authentication. If the <CODE>user</CODE> argument is <CODE>NULL</CODE>
5089  then the current login user is used.</P>
5090 <H3><A NAME="10_32_4">Example</A></H3>
5091 <PRE>
5092 #include &lt;cups/cups.h&gt;
5093
5094 ...
5095
5096 cupsSetUser(&quot;root&quot;);
5097 </PRE>
5098 <H3><A NAME="10_32_5">See Also</A></H3>
5099 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5100  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
5101 HREF="#cupsUser()"> cupsUser()</A>
5102 <!-- NEW PAGE -->
5103 </P>
5104 <H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
5105 <H3><A NAME="10_33_1">Usage</A></H3>
5106 <PRE>
5107 char *
5108 cupsTempFile(char *filename,
5109              int length);
5110 </PRE>
5111 <H3><A NAME="10_33_2">Arguments</A></H3>
5112 <CENTER>
5113 <TABLE BORDER WIDTH="80%">
5114 <TR><TH>Argument</TH><TH>Description</TH></TR>
5115 <TR><TD>filename</TD><TD>The character string to hold the temporary
5116  filename.</TD></TR>
5117 <TR><TD>length</TD><TD>The size of the filename string in bytes.</TD></TR>
5118 </TABLE>
5119 </CENTER>
5120 <H3><A NAME="10_33_3">Returns</A></H3>
5121 <P>A pointer to <CODE>filename</CODE>.</P>
5122 <H3><A NAME="10_33_4">Description</A></H3>
5123 <P><CODE>cupsTempFile()</CODE> generates a temporary filename for the<VAR>
5124  /var/tmp</VAR> directory or the directory specified by the <CODE>TMPDIR</CODE>
5125  environment variable.</P>
5126 <H3><A NAME="10_33_5">Example</A></H3>
5127 <PRE>
5128 #include &lt;cups/cups.h&gt;
5129
5130 char filename[256];
5131
5132 cupsTempFile(filename, sizeof(filename));
5133 </PRE>
5134
5135 <!-- NEW PAGE -->
5136 <H2><A NAME="cupsUser">cupsUser()</A></H2>
5137 <H3><A NAME="10_34_1">Usage</A></H3>
5138 <PRE>
5139 const char *
5140 cupsUser(void);
5141 </PRE>
5142 <H3><A NAME="10_34_2">Returns</A></H3>
5143 <P>A pointer to the current username or <CODE>NULL</CODE> if the user ID
5144  is undefined.</P>
5145 <H3><A NAME="10_34_3">Description</A></H3>
5146 <P><CODE>cupsUser()</CODE> returns the name associated with the current
5147  user ID as reported by the <CODE>getuid()</CODE> system call.</P>
5148 <H3><A NAME="10_34_4">Example</A></H3>
5149 <PRE>
5150 #include &lt;cups/cups.h&gt;
5151
5152 const char *user;
5153
5154 user = cupsUser();
5155 </PRE>
5156 <H3><A NAME="10_34_5">See Also</A></H3>
5157 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsServer">
5158  cupsServer()</A>
5159 <!-- NEW PAGE -->
5160 </P>
5161 <H2><A NAME="httpBlocking">httpBlocking()</A></H2>
5162 <H3><A NAME="10_35_1">Usage</A></H3>
5163 <PRE>
5164 void httpBlocking(http_t *http, int blocking)
5165 </PRE>
5166 <H3><A NAME="10_35_2">Arguments</A></H3>
5167 <CENTER>
5168 <TABLE BORDER WIDTH="80%">
5169 <TR><TH>Argument</TH><TH>Description</TH></TR>
5170 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5171 <TR><TD>blocking</TD><TD>0 if the connection should be non-blocking, 1
5172  if it should be blocking</TD></TR>
5173 </TABLE>
5174 </CENTER>
5175 <H3><A NAME="10_35_3">Description</A></H3>
5176 <P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for
5177  the HTTP connection. By default HTTP connections will block (stop) the
5178  client program until data is available or can be sent to the server.</P>
5179 <H3><A NAME="10_35_4">Example</A></H3>
5180 <PRE>
5181 #include &lt;cups/http.h&gt;
5182
5183 http_t *http;
5184
5185 http = httpConnect(&quot;server&quot;, port);
5186 httpBlocking(http, 0);
5187 </PRE>
5188 <H3><A NAME="10_35_5">See Also</A></H3>
5189 <A HREF="#httpCheck"> <CODE>httpCheck()</CODE></A>,<A HREF="#httpConnect">
5190  <CODE>httpConnect()</CODE></A>
5191 <!-- NEW PAGE -->
5192
5193 <H2><A NAME="httpCheck">httpCheck()</A></H2>
5194 <H3><A NAME="10_36_1">Usage</A></H3>
5195 <PRE>
5196 int httpCheck(http_t *http);
5197 </PRE>
5198 <H3><A NAME="10_36_2">Arguments</A></H3>
5199 <CENTER>
5200 <TABLE BORDER WIDTH="80%">
5201 <TR><TH>Argument</TH><TH>Description</TH></TR>
5202 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5203 </TABLE>
5204 </CENTER>
5205 <H3><A NAME="10_36_3">Returns</A></H3>
5206 <P>0 if there is no data pending, 1 otherwise.</P>
5207 <H3><A NAME="10_36_4">Description</A></H3>
5208 <P>The <CODE>httpCheck()</CODE> function checks to see if there is any
5209  data pending on an HTTP connection.</P>
5210 <H3><A NAME="10_36_5">Example</A></H3>
5211 <PRE>
5212 #include &lt;cups/http.h&gt;
5213
5214 http_t *http;
5215
5216 if (httpCheck(http))
5217 {
5218   ... do something ...
5219 }
5220 </PRE>
5221 <H3><A NAME="10_36_6">See Also</A></H3>
5222 <A HREF="#httpBlocking"> <CODE>httpBlocking()</CODE></A>,<A HREF="#httpConnect">
5223  <CODE>httpConnect()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE>
5224 </A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE></A>
5225 <!-- NEW PAGE -->
5226
5227 <H2><A NAME="httpClearFields">httpClearFields()</A></H2>
5228 <H3><A NAME="10_37_1">Usage</A></H3>
5229 <PRE>
5230 void httpClearFields(http_t *http)
5231 </PRE>
5232 <H3><A NAME="10_37_2">Arguments</A></H3>
5233 <CENTER>
5234 <TABLE BORDER WIDTH="80%">
5235 <TR><TH>Argument</TH><TH>Description</TH></TR>
5236 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5237 </TABLE>
5238 </CENTER>
5239 <H3><A NAME="10_37_3">Description</A></H3>
5240 <P>The <CODE>httpClearFields()</CODE> function clears all HTTP request
5241  fields for the HTTP connection.</P>
5242 <H3><A NAME="10_37_4">Example</A></H3>
5243 <PRE>
5244 #include &lt;cups/http.h&gt;
5245
5246 http_t *http;
5247
5248 httpClearFields(http);
5249 </PRE>
5250 <H3><A NAME="10_37_5">See Also</A></H3>
5251 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
5252  <CODE>httpGetField()</CODE></A>,<A HREF="#httpSetField"> <CODE>
5253 httpSetField()</CODE></A>
5254 <!-- NEW PAGE -->
5255
5256 <H2><A NAME="httpClose">httpClose()</A></H2>
5257 <H3><A NAME="10_38_1">Usage</A></H3>
5258 <PRE>
5259 void httpClose(http_t *http);
5260 </PRE>
5261 <H3><A NAME="10_38_2">Arguments</A></H3>
5262 <CENTER>
5263 <TABLE BORDER WIDTH="80%">
5264 <TR><TH>Argument</TH><TH>Description</TH></TR>
5265 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5266 </TABLE>
5267 </CENTER>
5268 <H3><A NAME="10_38_3">Description</A></H3>
5269 <P>The <CODE>httpClose()</CODE> function closes an active HTTP
5270  connection.</P>
5271 <H3><A NAME="10_38_4">Example</A></H3>
5272 <PRE>
5273 #include &lt;cups/http.h&gt;
5274
5275 http_t *http;
5276
5277 httpClose(http);
5278 </PRE>
5279 <H3><A NAME="10_38_5">See Also</A></H3>
5280 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5281 <!-- NEW PAGE -->
5282
5283 <H2><A NAME="httpConnect">httpConnect()</A></H2>
5284 <H3><A NAME="10_39_1">Usage</A></H3>
5285 <PRE>
5286 http_t *httpConnect(const char *hostname, int port);
5287 </PRE>
5288 <H3><A NAME="10_39_2">Arguments</A></H3>
5289 <CENTER>
5290 <TABLE BORDER WIDTH="80%">
5291 <TR><TH>Argument</TH><TH>Description</TH></TR>
5292 <TR><TD>hostname</TD><TD>The name or IP address of the server to connect
5293  to</TD></TR>
5294 <TR><TD>port</TD><TD>The port number to use</TD></TR>
5295 </TABLE>
5296 </CENTER>
5297 <H3><A NAME="10_39_3">Returns</A></H3>
5298 <P>A pointer to a HTTP connection structure or NULL if the connection
5299  could not be made.</P>
5300 <H3><A NAME="10_39_4">Description</A></H3>
5301 <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to
5302  the specified server and port.</P>
5303 <H3><A NAME="10_39_5">Example</A></H3>
5304 <PRE>
5305 #include &lt;cups/http.h&gt;
5306
5307 http_t *http;
5308
5309 http = httpConnect(cupsServer(), ippPort());
5310 </PRE>
5311 <H3><A NAME="10_39_6">See Also</A></H3>
5312 <A HREF="#httpClose"> <CODE>httpClose()</CODE></A>,<A HREF="#httpGet"> <CODE>
5313 httpGet()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE></A>,<A HREF="#httpPost">
5314  <CODE>httpPost()</CODE></A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE>
5315 </A>,<A HREF="#httpWrite"> <CODE>httpWrite()</CODE></A>
5316 <!-- NEW PAGE -->
5317
5318 <H2><A NAME="httpDecode64">httpDecode64()</A></H2>
5319 <H3><A NAME="10_40_1">Usage</A></H3>
5320 <PRE>
5321 char *httpDecode64(char *out, const char *in);
5322 </PRE>
5323 <H3><A NAME="10_40_2">Arguments</A></H3>
5324 <CENTER>
5325 <TABLE BORDER WIDTH="80%">
5326 <TR><TH>Argument</TH><TH>Description</TH></TR>
5327 <TR><TD>out</TD><TD>The output string</TD></TR>
5328 <TR><TD>in</TD><TD>The input string</TD></TR>
5329 </TABLE>
5330 </CENTER>
5331 <H3><A NAME="10_40_3">Returns</A></H3>
5332 <P>A pointer to the decoded string.</P>
5333 <H3><A NAME="10_40_4">Description</A></H3>
5334 <P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded
5335  string to the original string.</P>
5336 <H3><A NAME="10_40_5">Example</A></H3>
5337 <PRE>
5338 #include &lt;cups/http.h&gt;
5339
5340 char encoded_string[255];
5341 char original_string[255];
5342
5343 httpDecode64(original_string, encoded_string);
5344 </PRE>
5345 <H3><A NAME="10_40_6">See Also</A></H3>
5346 <A HREF="#httpEncode64"> <CODE>httpEncode64()</CODE></A>
5347 <!-- NEW PAGE -->
5348
5349 <H2><A NAME="httpDelete">httpDelete()</A></H2>
5350 <H3><A NAME="10_41_1">Usage</A></H3>
5351 <PRE>
5352 int httpDelete(http_t *http, const char *uri);
5353 </PRE>
5354 <H3><A NAME="10_41_2">Arguments</A></H3>
5355 <CENTER>
5356 <TABLE BORDER WIDTH="80%">
5357 <TR><TH>Argument</TH><TH>Description</TH></TR>
5358 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5359 <TR><TD>uri</TD><TD>The URI to delete</TD></TR>
5360 </TABLE>
5361 </CENTER>
5362 <H3><A NAME="10_41_3">Returns</A></H3>
5363 <P>0 on success, non-zero on failure.</P>
5364 <H3><A NAME="10_41_4">Description</A></H3>
5365 <P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
5366  the server.</P>
5367 <H3><A NAME="10_41_5">Example</A></H3>
5368 <PRE>
5369 #include &lt;cups/http.h&gt;
5370
5371 http_t *http;
5372
5373 httpDelete(http, &quot;/some/uri&quot;);
5374 </PRE>
5375 <H3><A NAME="10_41_6">See Also</A></H3>
5376 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5377  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5378 httpUpdate()</CODE></A>
5379 <!-- NEW PAGE -->
5380
5381 <H2><A NAME="httpEncode64">httpEncode64()</A></H2>
5382 <H3><A NAME="10_42_1">Usage</A></H3>
5383 <PRE>
5384 char *httpEncode64(char *out, const char *in);
5385 </PRE>
5386 <H3><A NAME="10_42_2">Arguments</A></H3>
5387 <CENTER>
5388 <TABLE BORDER WIDTH="80%">
5389 <TR><TH>Argument</TH><TH>Description</TH></TR>
5390 <TR><TD>out</TD><TD>The output string</TD></TR>
5391 <TR><TD>in</TD><TD>The input string</TD></TR>
5392 </TABLE>
5393 </CENTER>
5394 <H3><A NAME="10_42_3">Returns</A></H3>
5395 <P>A pointer to the encoded string.</P>
5396 <H3><A NAME="10_42_4">Description</A></H3>
5397 <P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded
5398  string to the original string.</P>
5399 <H3><A NAME="10_42_5">Example</A></H3>
5400 <PRE>
5401 #include &lt;cups/http.h&gt;
5402
5403 char encoded_string[255];
5404 char original_string[255];
5405
5406 httpEncode64(encoded_string, original_string);
5407 </PRE>
5408 <H3><A NAME="10_42_6">See Also</A></H3>
5409 <A HREF="#httpDecode64"> <CODE>httpDecode64()</CODE></A>
5410 <!-- NEW PAGE -->
5411
5412 <H2><A NAME="httpError">httpError()</A></H2>
5413 <H3><A NAME="10_43_1">Usage</A></H3>
5414 <PRE>
5415 int httpError(http_t *http);
5416 </PRE>
5417 <H3><A NAME="10_43_2">Arguments</A></H3>
5418 <CENTER>
5419 <TABLE BORDER WIDTH="80%">
5420 <TR><TH>Argument</TH><TH>Description</TH></TR>
5421 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5422 </TABLE>
5423 </CENTER>
5424 <H3><A NAME="10_43_3">Returns</A></H3>
5425 <P>The last error that occurred or 0 if no error has occurred.</P>
5426 <H3><A NAME="10_43_4">Description</A></H3>
5427 <P>The <CODE>httpError()</CODE> function returns the last error that
5428  occurred on the HTTP connection.</P>
5429 <H3><A NAME="10_43_5">Example</A></H3>
5430 <PRE>
5431 #include &lt;cups/http.h&gt;
5432
5433 http_t *http;
5434
5435 if (httpError(http))
5436 {
5437   ... show an error message ...
5438 }
5439 </PRE>
5440 <H3><A NAME="10_43_6">See Also</A></H3>
5441 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5442 <!-- NEW PAGE -->
5443
5444 <H2><A NAME="httpFlush">httpFlush()</A></H2>
5445 <H3><A NAME="10_44_1">Usage</A></H3>
5446 <PRE>
5447 void httpFlush(http_t *http);
5448 </PRE>
5449 <H3><A NAME="10_44_2">Arguments</A></H3>
5450 <CENTER>
5451 <TABLE BORDER WIDTH="80%">
5452 <TR><TH>Argument</TH><TH>Description</TH></TR>
5453 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5454 </TABLE>
5455 </CENTER>
5456 <H3><A NAME="10_44_3">Description</A></H3>
5457 <P>The <CODE>httpFlush()</CODE> function flushes any remaining data left
5458  from a GET or POST operation.</P>
5459 <H3><A NAME="10_44_4">Example</A></H3>
5460 <PRE>
5461 #include &lt;cups/http.h&gt;
5462
5463 http_t *http;
5464
5465 httpFlush(http);
5466 </PRE>
5467 <H3><A NAME="10_44_5">See Also</A></H3>
5468 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,
5469 <!-- NEW PAGE -->
5470
5471 <H2><A NAME="httpGet">httpGet()</A></H2>
5472 <H3><A NAME="10_45_1">Usage</A></H3>
5473 <PRE>
5474 int httpGet(http_t *http, const char *uri);
5475 </PRE>
5476 <H3><A NAME="10_45_2">Arguments</A></H3>
5477 <CENTER>
5478 <TABLE BORDER WIDTH="80%">
5479 <TR><TH>Argument</TH><TH>Description</TH></TR>
5480 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5481 <TR><TD>uri</TD><TD>The URI to get</TD></TR>
5482 </TABLE>
5483 </CENTER>
5484 <H3><A NAME="10_45_3">Returns</A></H3>
5485 <P>0 on success, non-zero on failure.</P>
5486 <H3><A NAME="10_45_4">Description</A></H3>
5487 <P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
5488  server.</P>
5489 <H3><A NAME="10_45_5">Example</A></H3>
5490 <PRE>
5491 #include &lt;cups/http.h&gt;
5492
5493 http_t *http;
5494
5495 httpGet(http, &quot;/some/uri&quot;);
5496 </PRE>
5497 <H3><A NAME="10_45_6">See Also</A></H3>
5498 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5499  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5500 httpUpdate()</CODE></A>
5501 <!-- NEW PAGE -->
5502
5503 <H2><A NAME="httpGets">httpGets()</A></H2>
5504 <H3><A NAME="10_46_1">Usage</A></H3>
5505 <PRE>
5506 char *httpGets(char *line, int length, http_t *http)
5507 </PRE>
5508 <H3><A NAME="10_46_2">Arguments</A></H3>
5509 <CENTER>
5510 <TABLE BORDER WIDTH="80%">
5511 <TR><TH>Argument</TH><TH>Description</TH></TR>
5512 <TR><TD>line</TD><TD>The string to fill with a line from the HTTP
5513  connection</TD></TR>
5514 <TR><TD>length</TD><TD>The maximum length of the string</TD></TR>
5515 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5516 </TABLE>
5517 </CENTER>
5518 <H3><A NAME="10_46_3">Returns</A></H3>
5519 <P>A pointer to the string or NULL if no line could be retrieved.</P>
5520 <H3><A NAME="10_46_4">Description</A></H3>
5521 <P>The <CODE>httpGets()</CODE> function is used to read a request line
5522  from the HTTP connection. It is not normally used by a client program.</P>
5523 <H3><A NAME="10_46_5">Example</A></H3>
5524 <PRE>
5525 #include &lt;cups/http.h&gt;
5526
5527 http_t *http;
5528 char line[1024];
5529
5530 if (httpGets(line, sizeof(line), http))
5531 {
5532   ... process the line ...
5533 }
5534 </PRE>
5535 <H3><A NAME="10_46_6">See Also</A></H3>
5536 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpUpdate">
5537  <CODE>httpUpdate()</CODE></A>
5538 <!-- NEW PAGE -->
5539
5540 <H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
5541 <H3><A NAME="10_47_1">Usage</A></H3>
5542 <PRE>
5543 const char *httpGetDateString(time_t time)
5544 </PRE>
5545 <H3><A NAME="10_47_2">Arguments</A></H3>
5546 <CENTER>
5547 <TABLE BORDER WIDTH="80%">
5548 <TR><TH>Argument</TH><TH>Description</TH></TR>
5549 <TR><TD>time</TD><TD>The UNIX date/time value</TD></TR>
5550 </TABLE>
5551 </CENTER>
5552 <H3><A NAME="10_47_3">Returns</A></H3>
5553 <P>A pointer to a static string containing the HTTP date/time string for
5554  the specified UNIX time value.</P>
5555 <H3><A NAME="10_47_4">Description</A></H3>
5556 <P>The <CODE>httpGetDateString()</CODE> function generates a date/time
5557  string suitable for HTTP requests from a UNIX time value.</P>
5558 <H3><A NAME="10_47_5">Example</A></H3>
5559 <PRE>
5560 #include &lt;cups/http.h&gt;
5561
5562 puts(httpGetDateString(time(NULL)));
5563 </PRE>
5564 <H3><A NAME="10_47_6">See Also</A></H3>
5565 <A HREF="#httpGetDateTime"> <CODE>httpGetDateTime()</CODE></A>
5566 <!-- NEW PAGE -->
5567
5568 <H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
5569 <H3><A NAME="10_48_1">Usage</A></H3>
5570 <PRE>
5571 time_t httpGetDateTime(const char *date)
5572 </PRE>
5573 <H3><A NAME="10_48_2">Arguments</A></H3>
5574 <CENTER>
5575 <TABLE BORDER WIDTH="80%">
5576 <TR><TH>Argument</TH><TH>Description</TH></TR>
5577 <TR><TD>date</TD><TD>The HTTP date/time string</TD></TR>
5578 </TABLE>
5579 </CENTER>
5580 <H3><A NAME="10_48_3">Returns</A></H3>
5581 <P>A UNIX time value.</P>
5582 <H3><A NAME="10_48_4">Description</A></H3>
5583 <P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP date/time
5584  string to a UNIX time value.</P>
5585 <H3><A NAME="10_48_5">Example</A></H3>
5586 <PRE>
5587 #include &lt;cups/http.h&gt;
5588
5589 printf(&quot;%d\n&quot;, httpGetDateTime(&quot;Fri, 30 June 2000 12:34:56 GMT&quot;));
5590 </PRE>
5591 <H3><A NAME="10_48_6">See Also</A></H3>
5592 <A HREF="#httpGetDateString"> <CODE>httpGetDateString()</CODE></A>
5593 <!-- NEW PAGE -->
5594
5595 <H2><A NAME="httpGetField">httpGetField()</A></H2>
5596 <H3><A NAME="10_49_1">Usage</A></H3>
5597 <PRE>
5598 const char *httpGetField(http_t *http, http_field_t field);
5599 </PRE>
5600 <H3><A NAME="10_49_2">Arguments</A></H3>
5601 <CENTER>
5602 <TABLE BORDER WIDTH="80%">
5603 <TR><TH>Argument</TH><TH>Description</TH></TR>
5604 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5605 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
5606 </TABLE>
5607 </CENTER>
5608 <H3><A NAME="10_49_3">Returns</A></H3>
5609 <P>A pointer to the field value string.</P>
5610 <H3><A NAME="10_49_4">Description</A></H3>
5611 <P>The <CODE>httpGetField()</CODE> function returns the current value
5612  for the specified HTTP field.</P>
5613 <H3><A NAME="10_49_5">Example</A></H3>
5614 <PRE>
5615 #include &lt;cups/http.h&gt;
5616
5617 http_t *http;
5618
5619 httpGet(http, &quot;/some/uri&quot;);
5620 while (httpUpdate(http) == HTTP_CONTINUE);
5621
5622 puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
5623 </PRE>
5624 <H3><A NAME="10_49_6">See Also</A></H3>
5625 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5626  <CODE>httpSetField()</CODE></A>
5627 <!-- NEW PAGE -->
5628
5629 <H2><A NAME="httpHead">httpHead()</A></H2>
5630 <H3><A NAME="10_50_1">Usage</A></H3>
5631 <PRE>
5632 int httpHead(http_t *http, const char *uri);
5633 </PRE>
5634 <H3><A NAME="10_50_2">Arguments</A></H3>
5635 <CENTER>
5636 <TABLE BORDER WIDTH="80%">
5637 <TR><TH>Argument</TH><TH>Description</TH></TR>
5638 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5639 <TR><TD>uri</TD><TD>The URI to head</TD></TR>
5640 </TABLE>
5641 </CENTER>
5642 <H3><A NAME="10_50_3">Returns</A></H3>
5643 <P>0 on success, non-zero on failure.</P>
5644 <H3><A NAME="10_50_4">Description</A></H3>
5645 <P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
5646  server.</P>
5647 <H3><A NAME="10_50_5">Example</A></H3>
5648 <PRE>
5649 #include &lt;cups/http.h&gt;
5650
5651 http_t *http;
5652
5653 httpHead(http, &quot;/some/uri&quot;);
5654 </PRE>
5655 <H3><A NAME="10_50_6">See Also</A></H3>
5656 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5657  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5658 httpUpdate()</CODE></A>
5659 <!-- NEW PAGE -->
5660
5661 <H2><A NAME="httpInitialize">httpInitialize()</A></H2>
5662 <H3><A NAME="10_51_1">Usage</A></H3>
5663 <PRE>
5664 void httpInitialize(void);
5665 </PRE>
5666 <H3><A NAME="10_51_2">Description</A></H3>
5667 <P>The <CODE>httpInitialize()</CODE> function initializes the networking
5668  code as needed by the underlying platform. It is called automatically
5669  by the <CODE>httpConnect()</CODE> function.</P>
5670 <H3><A NAME="10_51_3">Example</A></H3>
5671 <PRE>
5672 #include &lt;cups/http.h&gt;
5673
5674 httpInitialize();
5675 </PRE>
5676 <H3><A NAME="10_51_4">See Also</A></H3>
5677 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5678 <!-- NEW PAGE -->
5679
5680 <H2><A NAME="httpOptions">httpOptions()</A></H2>
5681 <H3><A NAME="10_52_1">Usage</A></H3>
5682 <PRE>
5683 int httpOptions(http_t *http, const char *uri);
5684 </PRE>
5685 <H3><A NAME="10_52_2">Arguments</A></H3>
5686 <CENTER>
5687 <TABLE BORDER WIDTH="80%">
5688 <TR><TH>Argument</TH><TH>Description</TH></TR>
5689 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5690 <TR><TD>uri</TD><TD>The URI to check for options</TD></TR>
5691 </TABLE>
5692 </CENTER>
5693 <H3><A NAME="10_52_3">Returns</A></H3>
5694 <P>0 on success, non-zero on failure.</P>
5695 <H3><A NAME="10_52_4">Description</A></H3>
5696 <P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request
5697  to the server.</P>
5698 <H3><A NAME="10_52_5">Example</A></H3>
5699 <PRE>
5700 #include &lt;cups/http.h&gt;
5701
5702 http_t *http;
5703
5704 httpOptions(http, &quot;/some/uri&quot;);
5705 </PRE>
5706 <H3><A NAME="10_52_6">See Also</A></H3>
5707 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5708  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5709 httpUpdate()</CODE></A>
5710 <!-- NEW PAGE -->
5711
5712 <H2><A NAME="httpPost">httpPost()</A></H2>
5713 <H3><A NAME="10_53_1">Usage</A></H3>
5714 <PRE>
5715 int httpPost(http_t *http, const char *uri);
5716 </PRE>
5717 <H3><A NAME="10_53_2">Arguments</A></H3>
5718 <CENTER>
5719 <TABLE BORDER WIDTH="80%">
5720 <TR><TH>Argument</TH><TH>Description</TH></TR>
5721 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5722 <TR><TD>uri</TD><TD>The URI to post to</TD></TR>
5723 </TABLE>
5724 </CENTER>
5725 <H3><A NAME="10_53_3">Returns</A></H3>
5726 <P>0 on success, non-zero on failure.</P>
5727 <H3><A NAME="10_53_4">Description</A></H3>
5728 <P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
5729  server.</P>
5730 <H3><A NAME="10_53_5">Example</A></H3>
5731 <PRE>
5732 #include &lt;cups/http.h&gt;
5733
5734 http_t *http;
5735
5736 httpPost(http, &quot;/some/uri&quot;);
5737 </PRE>
5738 <H3><A NAME="10_53_6">See Also</A></H3>
5739 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5740  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5741 httpUpdate()</CODE></A>
5742 <!-- NEW PAGE -->
5743
5744 <H2><A NAME="httpPrintf">httpPrintf()</A></H2>
5745 <H3><A NAME="10_54_1">Usage</A></H3>
5746 <PRE>
5747 int httpPrintf(http_t *http, const char *format, ...);
5748 </PRE>
5749 <H3><A NAME="10_54_2">Arguments</A></H3>
5750 <CENTER>
5751 <TABLE BORDER WIDTH="80%">
5752 <TR><TH>Argument</TH><TH>Description</TH></TR>
5753 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5754 <TR><TD>format</TD><TD>A printf-style format string</TD></TR>
5755 </TABLE>
5756 </CENTER>
5757 <H3><A NAME="10_54_3">Returns</A></H3>
5758 <P>The number of bytes written.</P>
5759 <H3><A NAME="10_54_4">Description</A></H3>
5760 <P>The <CODE>httpPrintf()</CODE> function sends a formatted string to
5761  the HTTP connection. It is normally only used by the CUPS API and
5762  scheduler.</P>
5763 <H3><A NAME="10_54_5">Example</A></H3>
5764 <PRE>
5765 #include &lt;cups/http.h&gt;
5766
5767 http_t *http;
5768
5769 httpPrintf(http, &quot;GET / HTTP/1.1 \r\n&quot;);
5770 </PRE>
5771 <H3><A NAME="10_54_6">See Also</A></H3>
5772 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5773 <!-- NEW PAGE -->
5774
5775 <H2><A NAME="httpPut">httpPut()</A></H2>
5776 <H3><A NAME="10_55_1">Usage</A></H3>
5777 <PRE>
5778 int httpPut(http_t *http, const char *uri);
5779 </PRE>
5780 <H3><A NAME="10_55_2">Arguments</A></H3>
5781 <CENTER>
5782 <TABLE BORDER WIDTH="80%">
5783 <TR><TH>Argument</TH><TH>Description</TH></TR>
5784 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5785 <TR><TD>uri</TD><TD>The URI to put</TD></TR>
5786 </TABLE>
5787 </CENTER>
5788 <H3><A NAME="10_55_3">Returns</A></H3>
5789 <P>0 on success, non-zero on failure.</P>
5790 <H3><A NAME="10_55_4">Description</A></H3>
5791 <P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
5792  server.</P>
5793 <H3><A NAME="10_55_5">Example</A></H3>
5794 <PRE>
5795 #include &lt;cups/http.h&gt;
5796
5797 http_t *http;
5798
5799 httpDelete(http, &quot;/some/uri&quot;);
5800 </PRE>
5801 <H3><A NAME="10_55_6">See Also</A></H3>
5802 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5803  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5804 httpUpdate()</CODE></A>
5805 <!-- NEW PAGE -->
5806
5807 <H2><A NAME="httpRead">httpRead()</A></H2>
5808 <H3><A NAME="10_56_1">Usage</A></H3>
5809 <PRE>
5810 int httpRead(http_t *http, char *buffer, int length);
5811 </PRE>
5812 <H3><A NAME="10_56_2">Arguments</A></H3>
5813 <CENTER>
5814 <TABLE BORDER WIDTH="80%">
5815 <TR><TH>Argument</TH><TH>Description</TH></TR>
5816 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5817 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
5818 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
5819 </TABLE>
5820 </CENTER>
5821 <H3><A NAME="10_56_3">Returns</A></H3>
5822 <P>The number of bytes read or -1 on error.</P>
5823 <H3><A NAME="10_56_4">Description</A></H3>
5824 <P>The <CODE>httpRead()</CODE> function reads data from the HTTP
5825  connection, possibly the result of a GET or POST request.</P>
5826 <H3><A NAME="10_56_5">Example</A></H3>
5827 <PRE>
5828 #include &lt;cups/http.h&gt;
5829
5830 http_t *http;
5831 char buffer[1024];
5832 int  bytes;
5833
5834 httpGet(http, &quot;/&quot;);
5835 while (httpUpdate(http) != HTTP_CONTINUE);
5836 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
5837 {
5838   buffer[bytes] = '\0';
5839   fputs(buffer, stdout);
5840 }
5841 </PRE>
5842 <H3><A NAME="10_56_6">See Also</A></H3>
5843 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpWrite">
5844  <CODE>httpWrite()</CODE></A>
5845 <!-- NEW PAGE -->
5846
5847 <H2><A NAME="httpReconnect">httpReconnect()</A></H2>
5848 <H3><A NAME="10_57_1">Usage</A></H3>
5849 <PRE>
5850 int httpReconnect(http_t *http);
5851 </PRE>
5852 <H3><A NAME="10_57_2">Arguments</A></H3>
5853 <CENTER>
5854 <TABLE BORDER WIDTH="80%">
5855 <TR><TH>Argument</TH><TH>Description</TH></TR>
5856 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5857 </TABLE>
5858 </CENTER>
5859 <H3><A NAME="10_57_3">Returns</A></H3>
5860 <P>0 on success, non-zero on failure.</P>
5861 <H3><A NAME="10_57_4">Description</A></H3>
5862 <P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP
5863  server. This is usually done automatically if the HTTP functions detect
5864  that the server connection has terminated.</P>
5865 <H3><A NAME="10_57_5">Example</A></H3>
5866 <PRE>
5867 #include &lt;cups/http.h&gt;
5868
5869 http_t *http;
5870
5871 httpReconnect(http);
5872 </PRE>
5873 <H3><A NAME="10_57_6">See Also</A></H3>
5874 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5875 <!-- NEW PAGE -->
5876
5877 <H2><A NAME="httpSeparate">httpSeparate()</A></H2>
5878 <H3><A NAME="10_58_1">Usage</A></H3>
5879 <PRE>
5880 void httpSeparate(const char *uri, char *method,
5881                   char *username, char *host, int *port,
5882                   char *resource);
5883 </PRE>
5884 <H3><A NAME="10_58_2">Arguments</A></H3>
5885 <CENTER>
5886 <TABLE BORDER WIDTH="80%">
5887 <TR><TH>Argument</TH><TH>Description</TH></TR>
5888 <TR><TD>uri</TD><TD>The URI to separate</TD></TR>
5889 <TR><TD>method</TD><TD>The method (scheme) of the URI</TD></TR>
5890 <TR><TD>username</TD><TD>The username (and password) portion of the URI,
5891  if any</TD></TR>
5892 <TR><TD>host</TD><TD>The hostname portion of the URI, if any</TD></TR>
5893 <TR><TD>port</TD><TD>The port number for the URI, either as specified or
5894  as default for the method/scheme</TD></TR>
5895 <TR><TD>resource</TD><TD>The resource string, usually a filename on the
5896  server</TD></TR>
5897 </TABLE>
5898 </CENTER>
5899 <H3><A NAME="10_58_3">Description</A></H3>
5900 <P>The <CODE>httpSeparate()</CODE> function separates the specified URI
5901  into its component parts. The method, username, hostname, and resource
5902  strings should be at least <CODE>HTTP_MAX_URI</CODE> characters long to
5903  avoid potential buffer overflow problems.</P>
5904 <H3><A NAME="10_58_4">Example</A></H3>
5905 <PRE>
5906 char uri[HTTP_MAX_URI];
5907 char method[HTTP_MAX_URI];
5908 char username[HTTP_MAX_URI];
5909 char host[HTTP_MAX_URI];
5910 char resource[HTTP_MAX_URI];
5911 int port;
5912
5913 httpSeparate(uri, method, username, host, &amp;port, resource);
5914 </PRE>
5915 <H3><A NAME="10_58_5">See Also</A></H3>
5916 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5917 <!-- NEW PAGE -->
5918
5919 <H2><A NAME="httpSetField">httpSetField()</A></H2>
5920 <H3><A NAME="10_59_1">Usage</A></H3>
5921 <PRE>
5922 void httpSetField(http_t *http, http_field_t field, const char *value);
5923 </PRE>
5924 <H3><A NAME="10_59_2">Arguments</A></H3>
5925 <CENTER>
5926 <TABLE BORDER WIDTH="80%">
5927 <TR><TH>Argument</TH><TH>Description</TH></TR>
5928 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5929 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
5930 <TR><TD>value</TD><TD>The string value for the field</TD></TR>
5931 </TABLE>
5932 </CENTER>
5933 <H3><A NAME="10_59_3">Description</A></H3>
5934 <P>The <CODE>httpSetField()</CODE> function sets the current value for
5935  the specified HTTP field.</P>
5936 <H3><A NAME="10_59_4">Example</A></H3>
5937 <PRE>
5938 #include &lt;cups/http.h&gt;
5939
5940 http_t *http;
5941
5942 httpSetField(http, HTTP_FIELD_AUTHORIZATION, &quot;Basic dfdr34453454325&quot;));
5943 httpGet(http, &quot;/some/uri&quot;);
5944 while (httpUpdate(http) == HTTP_CONTINUE);
5945 </PRE>
5946 <H3><A NAME="10_59_5">See Also</A></H3>
5947 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
5948  <CODE>httpGetField()</CODE></A>
5949 <!-- NEW PAGE -->
5950
5951 <H2><A NAME="httpTrace">httpTrace()</A></H2>
5952 <H3><A NAME="10_60_1">Usage</A></H3>
5953 <PRE>
5954 int httpTrace(http_t *http, const char *uri);
5955 </PRE>
5956 <H3><A NAME="10_60_2">Arguments</A></H3>
5957 <CENTER>
5958 <TABLE BORDER WIDTH="80%">
5959 <TR><TH>Argument</TH><TH>Description</TH></TR>
5960 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5961 <TR><TD>uri</TD><TD>The URI to trace</TD></TR>
5962 </TABLE>
5963 </CENTER>
5964 <H3><A NAME="10_60_3">Returns</A></H3>
5965 <P>0 on success, non-zero on failure.</P>
5966 <H3><A NAME="10_60_4">Description</A></H3>
5967 <P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to
5968  the server.</P>
5969 <H3><A NAME="10_60_5">Example</A></H3>
5970 <PRE>
5971 #include &lt;cups/http.h&gt;
5972
5973 http_t *http;
5974
5975 httpTrace(http, &quot;/some/uri&quot;);
5976 </PRE>
5977 <H3><A NAME="10_60_6">See Also</A></H3>
5978 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5979  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5980 httpUpdate()</CODE></A>
5981 <!-- NEW PAGE -->
5982
5983 <H2><A NAME="httpUpdate">httpUpdate()</A></H2>
5984 <H3><A NAME="10_61_1">Usage</A></H3>
5985 <PRE>
5986 http_status_t httpUpdate(http_t *http);
5987 </PRE>
5988 <H3><A NAME="10_61_2">Arguments</A></H3>
5989 <CENTER>
5990 <TABLE BORDER WIDTH="80%">
5991 <TR><TH>Argument</TH><TH>Description</TH></TR>
5992 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5993 </TABLE>
5994 </CENTER>
5995 <H3><A NAME="10_61_3">Returns</A></H3>
5996 <P>The HTTP status of the current request.</P>
5997 <H3><A NAME="10_61_4">Description</A></H3>
5998 <P>The <CODE>httpUpdate()</CODE> function updates the current request
5999  status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or
6000  TRACE request to finalize the HTTP request and retrieve the request
6001  status.</P>
6002 <P>Since proxies and the current blocking mode can cause the request to
6003  take longer, programs should continue calling <CODE>httpUpdate()</CODE>
6004  until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>
6005 .</P>
6006 <H3><A NAME="10_61_5">Example</A></H3>
6007 <PRE>
6008 #include &lt;cups/http.h&gt;
6009
6010 http_t *http;
6011 http_status_t status;
6012
6013 httpGet(http, &quot;/some/uri&quot;);
6014 while ((status = httpUpdate(http)) == HTTP_CONTINUE);
6015 printf(&quot;Request status is %d\n&quot;, status);
6016 </PRE>
6017 <H3><A NAME="10_61_6">See Also</A></H3>
6018 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpDelete">
6019  <CODE>httpDelete()</CODE></A>,<A HREF="#httpGet"> <CODE>httpGet()</CODE>
6020 </A>,<A HREF="#httpHead"> <CODE>httpHead()</CODE></A>,<A HREF="#httpOptions">
6021  <CODE>httpOptions()</CODE></A>,<A HREF="#httpPost"> <CODE>httpPost()</CODE>
6022 </A>,<A HREF="#httpPut"> <CODE>httpPut()</CODE></A>,<A HREF="#httpTrace">
6023  <CODE>httpTrace()</CODE></A>
6024 <!-- NEW PAGE -->
6025
6026 <H2><A NAME="httpWrite">httpWrite()</A></H2>
6027 <H3><A NAME="10_62_1">Usage</A></H3>
6028 <PRE>
6029 int httpWrite(http_t *http, char *buffer, int length);
6030 </PRE>
6031 <H3><A NAME="10_62_2">Arguments</A></H3>
6032 <CENTER>
6033 <TABLE BORDER WIDTH="80%">
6034 <TR><TH>Argument</TH><TH>Description</TH></TR>
6035 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6036 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
6037 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
6038 </TABLE>
6039 </CENTER>
6040 <H3><A NAME="10_62_3">Returns</A></H3>
6041 <P>The number of bytes read or -1 on error.</P>
6042 <H3><A NAME="10_62_4">Description</A></H3>
6043 <P>The <CODE>httpWrite()</CODE> function reads data from the HTTP
6044  connection, possibly the result of a GET or POST request.</P>
6045 <H3><A NAME="10_62_5">Example</A></H3>
6046 <PRE>
6047 #include &lt;cups/http.h&gt;
6048
6049 http_t *http;
6050 FILE *fp;
6051 char buffer[1024];
6052 int  bytes;
6053
6054 httpPost(http, &quot;/&quot;);
6055
6056 while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) &gt; 0)
6057   httpWrite(http, buffer, bytes);
6058
6059 while (httpUpdate(http) != HTTP_CONTINUE);
6060
6061 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
6062 {
6063   buffer[bytes] = '\0';
6064   fputs(buffer, stdout);
6065 }
6066 </PRE>
6067 <H3><A NAME="10_62_6">See Also</A></H3>
6068 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpRead">
6069  <CODE>httpRead()</CODE></A>
6070 <!-- NEW PAGE -->
6071
6072 <H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
6073 <H3><A NAME="10_63_1">Usage</A></H3>
6074 <PRE>
6075 ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
6076                                const char *name, char value);
6077 </PRE>
6078 <H3><A NAME="10_63_2">Arguments</A></H3>
6079 <CENTER>
6080 <TABLE BORDER WIDTH="80%">
6081 <TR><TH>Argument</TH><TH>Description</TH></TR>
6082 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6083 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6084 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6085 <TR><TD>value</TD><TD>The boolean value</TD></TR>
6086 </TABLE>
6087 </CENTER>
6088 <H3><A NAME="10_63_3">Returns</A></H3>
6089 <P>A pointer to the new attribute or NULL if the attribute could not be
6090  created.</P>
6091 <H3><A NAME="10_63_4">Description</A></H3>
6092 <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean
6093  attribute value to the specified IPP request.</P>
6094 <H3><A NAME="10_63_5">Example</A></H3>
6095 <PRE>
6096 #include &lt;cups/ipp.h&gt;
6097
6098 ipp_t *ipp;
6099
6100 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;my-jobs&quot;, 1);
6101 </PRE>
6102 <H3><A NAME="10_63_6">See Also</A></H3>
6103 <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate">
6104  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6105 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6106 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6107 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6108  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6109 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6110 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6111 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6112 ippAddStrings()</CODE></A>
6113 <!-- NEW PAGE -->
6114
6115 <H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
6116 <H3><A NAME="10_64_1">Usage</A></H3>
6117 <PRE>
6118 ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
6119                                 const char *name, int num_values,
6120                                 const char *values);
6121 </PRE>
6122 <H3><A NAME="10_64_2">Arguments</A></H3>
6123 <CENTER>
6124 <TABLE BORDER WIDTH="80%">
6125 <TR><TH>Argument</TH><TH>Description</TH></TR>
6126 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6127 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6128 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6129 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6130 <TR><TD>values</TD><TD>The boolean values</TD></TR>
6131 </TABLE>
6132 </CENTER>
6133 <H3><A NAME="10_64_3">Returns</A></H3>
6134 <P>A pointer to the new attribute or NULL if the attribute could not be
6135  created.</P>
6136 <H3><A NAME="10_64_4">Description</A></H3>
6137 <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
6138  attribute values to the specified IPP request. If the <CODE>values</CODE>
6139  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6140  false values is created.</P>
6141 <H3><A NAME="10_64_5">Example</A></H3>
6142 <PRE>
6143 #include &lt;cups/ipp.h&gt;
6144
6145 ipp_t *ipp;
6146 char values[10];
6147
6148 ippAddBooleans(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 10, values);
6149 </PRE>
6150 <H3><A NAME="10_64_6">See Also</A></H3>
6151 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddDate">
6152  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6153 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6154 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6155 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6156  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6157 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6158 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6159 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6160 ippAddStrings()</CODE></A>
6161 <!-- NEW PAGE -->
6162
6163 <H2><A NAME="ippAddDate">ippAddDate()</A></H2>
6164 <H3><A NAME="10_65_1">Usage</A></H3>
6165 <PRE>
6166 ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group,
6167                             const char *name, ipp_uchar_t *value);
6168 </PRE>
6169 <H3><A NAME="10_65_2">Arguments</A></H3>
6170 <CENTER>
6171 <TABLE BORDER WIDTH="80%">
6172 <TR><TH>Argument</TH><TH>Description</TH></TR>
6173 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6174 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6175 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6176 <TR><TD>value</TD><TD>The date value</TD></TR>
6177 </TABLE>
6178 </CENTER>
6179 <H3><A NAME="10_65_3">Returns</A></H3>
6180 <P>A pointer to the new attribute or NULL if the attribute could not be
6181  created.</P>
6182 <H3><A NAME="10_65_4">Description</A></H3>
6183 <P>The <CODE>ippAddDate()</CODE> function adds a single date-time
6184  attribute value to the specified IPP request.</P>
6185 <H3><A NAME="10_65_5">Example</A></H3>
6186 <PRE>
6187 #include &lt;cups/ipp.h&gt;
6188
6189 ipp_t *ipp;
6190
6191 ippAddDate(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;,
6192            ippTimeToDate(time(NULL));
6193 </PRE>
6194 <H3><A NAME="10_65_6">See Also</A></H3>
6195 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6196  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6197 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6198 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6199 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6200  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6201 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6202 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6203 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6204 ippAddStrings()</CODE></A>,<A HREF="#ippTimeToDate"> <CODE>
6205 ippTimeToDate()</CODE></A>
6206 <!-- NEW PAGE -->
6207
6208 <H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
6209 <H3><A NAME="10_66_1">Usage</A></H3>
6210 <PRE>
6211 ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
6212                                ipp_tag_t tag, const char *name,
6213                                int value);
6214 </PRE>
6215 <H3><A NAME="10_66_2">Arguments</A></H3>
6216 <CENTER>
6217 <TABLE BORDER WIDTH="80%">
6218 <TR><TH>Argument</TH><TH>Description</TH></TR>
6219 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6220 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6221 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6222  IPP_TAG_ENUM)</TD></TR>
6223 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6224 <TR><TD>value</TD><TD>The integer value</TD></TR>
6225 </TABLE>
6226 </CENTER>
6227 <H3><A NAME="10_66_3">Returns</A></H3>
6228 <P>A pointer to the new attribute or NULL if the attribute could not be
6229  created.</P>
6230 <H3><A NAME="10_66_4">Description</A></H3>
6231 <P>The <CODE>ippAddInteger()</CODE> function adds a single integer
6232  attribute value to the specified IPP request.</P>
6233 <H3><A NAME="10_66_5">Example</A></H3>
6234 <PRE>
6235 #include &lt;cups/ipp.h&gt;
6236
6237 ipp_t *ipp;
6238
6239 ippAddInteger(ipp, IPP_TAG_OPERATION, &quot;limit&quot;, 100);
6240 </PRE>
6241 <H3><A NAME="10_66_6">See Also</A></H3>
6242 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6243  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6244 ippAddDate()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6245 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6246 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6247  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6248 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6249 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6250 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6251 ippAddStrings()</CODE></A>
6252 <!-- NEW PAGE -->
6253
6254 <H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
6255 <H3><A NAME="10_67_1">Usage</A></H3>
6256 <PRE>
6257 ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
6258                                 ipp_tag_t tag, const char *name,
6259                                 int num_values, const int *values);
6260 </PRE>
6261 <H3><A NAME="10_67_2">Arguments</A></H3>
6262 <CENTER>
6263 <TABLE BORDER WIDTH="80%">
6264 <TR><TH>Argument</TH><TH>Description</TH></TR>
6265 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6266 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6267 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6268  IPP_TAG_ENUM)</TD></TR>
6269 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6270 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6271 <TR><TD>values</TD><TD>The integer values</TD></TR>
6272 </TABLE>
6273 </CENTER>
6274 <H3><A NAME="10_67_3">Returns</A></H3>
6275 <P>A pointer to the new attribute or NULL if the attribute could not be
6276  created.</P>
6277 <H3><A NAME="10_67_4">Description</A></H3>
6278 <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
6279  attribute values to the specified IPP request. If the <CODE>values</CODE>
6280  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> 0
6281  values is created.</P>
6282 <H3><A NAME="10_67_5">Example</A></H3>
6283 <PRE>
6284 #include &lt;cups/ipp.h&gt;
6285
6286 ipp_t *ipp;
6287 int values[100];
6288
6289 ippAddIntegers(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 100, values);
6290 </PRE>
6291 <H3><A NAME="10_67_6">See Also</A></H3>
6292 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6293  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6294 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6295 </A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges">
6296  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6297 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6298 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6299 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6300 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6301 ippAddStrings()</CODE></A>
6302 <!-- NEW PAGE -->
6303
6304 <H2><A NAME="ippAddRange">ippAddRange()</A></H2>
6305 <H3><A NAME="10_68_1">Usage</A></H3>
6306 <PRE>
6307 ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group,
6308                              const char *name, int low,
6309                              int high);
6310 </PRE>
6311 <H3><A NAME="10_68_2">Arguments</A></H3>
6312 <CENTER>
6313 <TABLE BORDER WIDTH="80%">
6314 <TR><TH>Argument</TH><TH>Description</TH></TR>
6315 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6316 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6317 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6318 <TR><TD>low</TD><TD>The lower value</TD></TR>
6319 <TR><TD>high</TD><TD>The higher value</TD></TR>
6320 </TABLE>
6321 </CENTER>
6322 <H3><A NAME="10_68_3">Returns</A></H3>
6323 <P>A pointer to the new attribute or NULL if the attribute could not be
6324  created.</P>
6325 <H3><A NAME="10_68_4">Description</A></H3>
6326 <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
6327  value to the specified IPP request.</P>
6328 <H3><A NAME="10_68_5">Example</A></H3>
6329 <PRE>
6330 #include &lt;cups/ipp.h&gt;
6331
6332 ipp_t *ipp;
6333
6334 ippAddRange(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 1, 10);
6335 </PRE>
6336 <H3><A NAME="10_68_6">See Also</A></H3>
6337 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6338  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6339 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6340 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRanges">
6341  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6342 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6343 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6344 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6345 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6346 ippAddStrings()</CODE></A>
6347 <!-- NEW PAGE -->
6348
6349 <H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
6350 <H3><A NAME="10_69_1">Usage</A></H3>
6351 <PRE>
6352 ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
6353                               const char *name, int num_values,
6354                               const int *lows, const int *highs);
6355 </PRE>
6356 <H3><A NAME="10_69_2">Arguments</A></H3>
6357 <CENTER>
6358 <TABLE BORDER WIDTH="80%">
6359 <TR><TH>Argument</TH><TH>Description</TH></TR>
6360 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6361 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6362 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6363 <TR><TD>num_values</TD><TD>The number of range values</TD></TR>
6364 <TR><TD>lows</TD><TD>The lower values</TD></TR>
6365 <TR><TD>highs</TD><TD>The higher values</TD></TR>
6366 </TABLE>
6367 </CENTER>
6368 <H3><A NAME="10_69_3">Returns</A></H3>
6369 <P>A pointer to the new attribute or NULL if the attribute could not be
6370  created.</P>
6371 <H3><A NAME="10_69_4">Description</A></H3>
6372 <P>The <CODE>ippAddRanges()</CODE> function adds one or more range
6373  attribute values to the specified IPP request. If the <CODE>values</CODE>
6374  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6375  0,0 ranges is created.</P>
6376 <H3><A NAME="10_69_5">Example</A></H3>
6377 <PRE>
6378 #include &lt;cups/ipp.h&gt;
6379
6380 ipp_t *ipp;
6381 int lows[2];
6382 int highs[2];
6383
6384 ippAddRanges(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 2, lows, highs);
6385 </PRE>
6386 <H3><A NAME="10_69_6">See Also</A></H3>
6387 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6388  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6389 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6390 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6391  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6392 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6393 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6394 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6395 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6396 ippAddStrings()</CODE></A>
6397 <!-- NEW PAGE -->
6398
6399 <H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
6400 <H3><A NAME="10_70_1">Usage</A></H3>
6401 <PRE>
6402 ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
6403                                   const char *name, int xres,
6404                                   int yres, ipp_res_t units);
6405 </PRE>
6406 <H3><A NAME="10_70_2">Arguments</A></H3>
6407 <CENTER>
6408 <TABLE BORDER WIDTH="80%">
6409 <TR><TH>Argument</TH><TH>Description</TH></TR>
6410 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6411 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6412 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6413 <TR><TD>xres</TD><TD>The horizontal resolution</TD></TR>
6414 <TR><TD>yres</TD><TD>The vertical resolution</TD></TR>
6415 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6416 </TABLE>
6417 </CENTER>
6418 <H3><A NAME="10_70_3">Returns</A></H3>
6419 <P>A pointer to the new attribute or NULL if the attribute could not be
6420  created.</P>
6421 <H3><A NAME="10_70_4">Description</A></H3>
6422 <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution
6423  attribute value to the specified IPP request.</P>
6424 <H3><A NAME="10_70_5">Example</A></H3>
6425 <PRE>
6426 #include &lt;cups/ipp.h&gt;
6427
6428 ipp_t *ipp;
6429
6430 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolution&quot;,
6431               720, 720, IPP_RES_PER_INCH);
6432 </PRE>
6433 <H3><A NAME="10_70_6">See Also</A></H3>
6434 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6435  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6436 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6437 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6438  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6439 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6440 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6441 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6442 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6443 ippAddStrings()</CODE></A>
6444 <!-- NEW PAGE -->
6445
6446 <H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
6447 <H3><A NAME="10_71_1">Usage</A></H3>
6448 <PRE>
6449 ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
6450                                    const char *name, int num_values,
6451                                    const int *xres, const int *yres,
6452                                    const ipp_res_t *units);
6453 </PRE>
6454 <H3><A NAME="10_71_2">Arguments</A></H3>
6455 <CENTER>
6456 <TABLE BORDER WIDTH="80%">
6457 <TR><TH>Argument</TH><TH>Description</TH></TR>
6458 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6459 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6460 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6461 <TR><TD>num_values</TD><TD>The number of resolution values</TD></TR>
6462 <TR><TD>xres</TD><TD>The horizontal resolutions</TD></TR>
6463 <TR><TD>yres</TD><TD>The vertical resolutions</TD></TR>
6464 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6465 </TABLE>
6466 </CENTER>
6467 <H3><A NAME="10_71_3">Returns</A></H3>
6468 <P>A pointer to the new attribute or NULL if the attribute could not be
6469  created.</P>
6470 <H3><A NAME="10_71_4">Description</A></H3>
6471 <P>The <CODE>ippAddResolutions()</CODE> function adds one or more
6472  resolution attribute values to the specified IPP request. If the <CODE>
6473 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6474 num_values</CODE> 0,0 resolutions is created.</P>
6475 <H3><A NAME="10_71_5">Example</A></H3>
6476 <PRE>
6477 #include &lt;cups/ipp.h&gt;
6478
6479 ipp_t *ipp;
6480 int xres[5];
6481 int yres[5];
6482 ipp_res_t units[5];
6483
6484 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolutions-supported&quot;,
6485               5, xres, yres, units);
6486 </PRE>
6487 <H3><A NAME="10_71_6">See Also</A></H3>
6488 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6489  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6490 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6491 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6492  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6493 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6494 ippAddResolution()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6495 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6496 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6497 ippAddStrings()</CODE></A>
6498 <!-- NEW PAGE -->
6499
6500 <H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
6501 <H3><A NAME="10_72_1">Usage</A></H3>
6502 <PRE>
6503 ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
6504 </PRE>
6505 <H3><A NAME="10_72_2">Arguments</A></H3>
6506 <CENTER>
6507 <TABLE BORDER WIDTH="80%">
6508 <TR><TH>Argument</TH><TH>Description</TH></TR>
6509 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6510 </TABLE>
6511 </CENTER>
6512 <H3><A NAME="10_72_3">Returns</A></H3>
6513 <P>A pointer to the new separator or NULL if the separator could not be
6514  created.</P>
6515 <H3><A NAME="10_72_4">Description</A></H3>
6516 <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator to
6517  the specified IPP request.</P>
6518 <H3><A NAME="10_72_5">Example</A></H3>
6519 <PRE>
6520 #include &lt;cups/ipp.h&gt;
6521
6522 ipp_t *ipp;
6523
6524 ippAddSeparator(ipp);
6525 </PRE>
6526 <H3><A NAME="10_72_6">See Also</A></H3>
6527 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6528  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6529 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6530 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6531  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6532 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6533 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6534 ippAddResolutions()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6535 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6536 ippAddStrings()</CODE></A>
6537 <!-- NEW PAGE -->
6538
6539 <H2><A NAME="ippAddString">ippAddString()</A></H2>
6540 <H3><A NAME="10_73_1">Usage</A></H3>
6541 <PRE>
6542 ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group,
6543                               ipp_tag_t tag, const char *name,
6544                               const char *charset, const char *value);
6545 </PRE>
6546 <H3><A NAME="10_73_2">Arguments</A></H3>
6547 <CENTER>
6548 <TABLE BORDER WIDTH="80%">
6549 <TR><TH>Argument</TH><TH>Description</TH></TR>
6550 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6551 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6552 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6553 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6554 <TR><TD>charset</TD><TD>The character set for the string</TD></TR>
6555 <TR><TD>value</TD><TD>The string value</TD></TR>
6556 </TABLE>
6557 </CENTER>
6558 <H3><A NAME="10_73_3">Returns</A></H3>
6559 <P>A pointer to the new attribute or NULL if the attribute could not be
6560  created.</P>
6561 <H3><A NAME="10_73_4">Description</A></H3>
6562 <P>The <CODE>ippAddString()</CODE> function adds a single string
6563  attribute value to the specified IPP request. For <CODE>
6564 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6565  charset value is provided with the string to identify the string
6566  encoding used. Otherwise the charset value is ignored.</P>
6567 <H3><A NAME="10_73_5">Example</A></H3>
6568 <PRE>
6569 #include &lt;cups/ipp.h&gt;
6570
6571 ipp_t *ipp;
6572
6573 ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;job-name&quot;,
6574              NULL, &quot;abc123&quot;);
6575 </PRE>
6576 <H3><A NAME="10_73_6">See Also</A></H3>
6577 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6578  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6579 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6580 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6581  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6582 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6583 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6584 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6585 ippAddSeparator()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6586 ippAddStrings()</CODE></A>
6587 <!-- NEW PAGE -->
6588
6589 <H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
6590 <H3><A NAME="10_74_1">Usage</A></H3>
6591 <PRE>
6592 ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
6593                                ipp_tag_t tag, const char *name,
6594                                int num_values, const char *charset,
6595                                const char **values);
6596 </PRE>
6597 <H3><A NAME="10_74_2">Arguments</A></H3>
6598 <CENTER>
6599 <TABLE BORDER WIDTH="80%">
6600 <TR><TH>Argument</TH><TH>Description</TH></TR>
6601 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6602 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6603 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6604 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6605 <TR><TD>num_values</TD><TD>The number of strings</TD></TR>
6606 <TR><TD>charset</TD><TD>The character set for the strings</TD></TR>
6607 <TR><TD>values</TD><TD>The string values</TD></TR>
6608 </TABLE>
6609 </CENTER>
6610 <H3><A NAME="10_74_3">Returns</A></H3>
6611 <P>A pointer to the new attribute or NULL if the attribute could not be
6612  created.</P>
6613 <H3><A NAME="10_74_4">Description</A></H3>
6614 <P>The <CODE>ippAddStrings()</CODE> function adds one or more string
6615  attribute values to the specified IPP request. For <CODE>
6616 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6617  charset value is provided with the strings to identify the string
6618  encoding used. Otherwise the charset value is ignored. If the <CODE>
6619 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6620 num_values</CODE> NULL strings is created.</P>
6621 <H3><A NAME="10_74_5">Example</A></H3>
6622 <PRE>
6623 #include &lt;cups/ipp.h&gt;
6624
6625 ipp_t *ipp;
6626 char *values[2] = { &quot;one&quot;, &quot;two&quot; };
6627
6628 ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, &quot;attr-name&quot;,
6629               2, NULL, values);
6630 </PRE>
6631 <H3><A NAME="10_74_6">See Also</A></H3>
6632 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6633  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6634 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6635 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6636  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6637 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6638 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6639 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6640 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6641 ippAddString()</CODE></A>
6642 <!-- NEW PAGE -->
6643
6644 <H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
6645 <H3><A NAME="10_75_1">Usage</A></H3>
6646 <PRE>
6647 time_t ippDateToTime(const ipp_uchar_t date[11]);
6648 </PRE>
6649 <H3><A NAME="10_75_2">Arguments</A></H3>
6650 <CENTER>
6651 <TABLE BORDER WIDTH="80%">
6652 <TR><TH>Argument</TH><TH>Description</TH></TR>
6653 <TR><TD>date</TD><TD>The IPP date-time value</TD></TR>
6654 </TABLE>
6655 </CENTER>
6656 <H3><A NAME="10_75_3">Returns</A></H3>
6657 <P>A UNIX time value.</P>
6658 <H3><A NAME="10_75_4">Description</A></H3>
6659 <P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time
6660  value to a UNIX time value.</P>
6661 <H3><A NAME="10_75_5">Example</A></H3>
6662 <PRE>
6663 #include &lt;cups/ipp.h&gt;
6664
6665 ipp_uchar_t date[11];
6666
6667 printf(&quot;UNIX time is %d\n&quot;, ippDateToTime(date));
6668 </PRE>
6669 <H3><A NAME="10_75_6">See Also</A></H3>
6670 <A HREF="#ippTimeToDate"> <CODE>ippTimeToDate()</CODE></A>
6671 <!-- NEW PAGE -->
6672
6673 <H2><A NAME="ippDelete">ippDelete()</A></H2>
6674 <H3><A NAME="10_76_1">Usage</A></H3>
6675 <PRE>
6676 void ippDelete(ipp_t *ipp);
6677 </PRE>
6678 <H3><A NAME="10_76_2">Arguments</A></H3>
6679 <CENTER>
6680 <TABLE BORDER WIDTH="80%">
6681 <TR><TH>Argument</TH><TH>Description</TH></TR>
6682 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6683 </TABLE>
6684 </CENTER>
6685 <H3><A NAME="10_76_3">Description</A></H3>
6686 <P>The <CODE>ippDelete()</CODE> function deletes all memory used by an
6687  IPP request or response.</P>
6688 <H3><A NAME="10_76_4">Example</A></H3>
6689 <PRE>
6690 #include &lt;cups/ipp.h&gt;
6691
6692 ipp_t *ipp;
6693
6694 ippDelete(ipp);
6695 </PRE>
6696 <H3><A NAME="10_76_5">See Also</A></H3>
6697 <A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6698 <!-- NEW PAGE -->
6699
6700 <H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
6701 <H3><A NAME="10_77_1">Usage</A></H3>
6702 <PRE>
6703 ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);
6704 </PRE>
6705 <H3><A NAME="10_77_2">Arguments</A></H3>
6706 <CENTER>
6707 <TABLE BORDER WIDTH="80%">
6708 <TR><TH>Argument</TH><TH>Description</TH></TR>
6709 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6710 <TR><TD>name</TD><TD>The name of the attribute</TD></TR>
6711 <TR><TD>tag</TD><TD>The required value tag for the attribute or <CODE>
6712 IPP_TAG_ZERO</CODE> for any type of value.</TD></TR>
6713 </TABLE>
6714 </CENTER>
6715 <H3><A NAME="10_77_3">Returns</A></H3>
6716 <P>A pointer to the first occurrence of the requested attribute, or <CODE>
6717 NULL</CODE> if it was not found.</P>
6718 <H3><A NAME="10_77_4">Description</A></H3>
6719 <P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the
6720  named attribute. The <CODE>tag</CODE> parameter restricts the search to
6721  a specific value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value
6722  with the name.</P>
6723 <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
6724  match the name/text values with or without the language code.</P>
6725 <H3><A NAME="10_77_5">Example</A></H3>
6726 <PRE>
6727 ipp_attribute_t *attr;
6728
6729 attr = ippFindAttribute(response, &quot;printer-state-message&quot;, IPP_TAG_TEXT);
6730 </PRE>
6731 <H3><A NAME="10_77_6">See Also</A></H3>
6732 <A HREF="#cupsDoFileRequest"> <CODE>cupsDoFileRequest()</CODE></A>,<A HREF="#cupsDoRequest">
6733  <CODE>cupsDoRequest()</CODE></A>,<A HREF="#ippDelete"> <CODE>
6734 ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6735 <!-- NEW PAGE -->
6736
6737 <H2><A NAME="ippLength">ippLength()</A></H2>
6738 <H3><A NAME="10_78_1">Usage</A></H3>
6739 <PRE>
6740 int ippLength(ipp_t *ipp);
6741 </PRE>
6742 <H3><A NAME="10_78_2">Arguments</A></H3>
6743 <CENTER>
6744 <TABLE BORDER WIDTH="80%">
6745 <TR><TH>Argument</TH><TH>Description</TH></TR>
6746 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6747 </TABLE>
6748 </CENTER>
6749 <H3><A NAME="10_78_3">Returns</A></H3>
6750 <P>The total encoded length of the IPP request or response in bytes.</P>
6751 <H3><A NAME="10_78_4">Description</A></H3>
6752 <P><CODE>ippLength()</CODE> returns the length of the IPP request or
6753  response in bytes.</P>
6754 <H3><A NAME="10_78_5">Example</A></H3>
6755 <PRE>
6756 printf(&quot;The length of the response is %d bytes.\n&quot;, ippLength(response));
6757 </PRE>
6758 <H3><A NAME="10_78_6">See Also</A></H3>
6759 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>
6760 ippNew()</CODE></A>
6761 <!-- NEW PAGE -->
6762
6763 <H2><A NAME="ippNew">ippNew()</A></H2>
6764 <H3><A NAME="10_79_1">Usage</A></H3>
6765 <PRE>
6766 ipp_t *ippNew(void);
6767 </PRE>
6768 <H3><A NAME="10_79_2">Returns</A></H3>
6769 <P>A pointer to a new IPP request or response.</P>
6770 <H3><A NAME="10_79_3">Description</A></H3>
6771 <P>The <CODE>ippNew()</CODE> function creates a new IPP request or
6772  response.</P>
6773 <H3><A NAME="10_79_4">Example</A></H3>
6774 <PRE>
6775 #include &lt;cups/ipp.h&gt;
6776
6777 ipp_t *ipp;
6778
6779 ipp = ippNew();
6780 </PRE>
6781 <H3><A NAME="10_79_5">See Also</A></H3>
6782 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>
6783 <!-- NEW PAGE -->
6784
6785 <H2><A NAME="ippPort">ippPort()</A></H2>
6786 <H3><A NAME="10_80_1">Usage</A></H3>
6787 <PRE>
6788 int ippPort(void);
6789 </PRE>
6790 <H3><A NAME="10_80_2">Returns</A></H3>
6791 <P>The default TCP/IP port number for IPP requests.</P>
6792 <H3><A NAME="10_80_3">Description</A></H3>
6793 <P>The <CODE>ippPort()</CODE> function returns the default IPP port
6794  number for requests.</P>
6795 <H3><A NAME="10_80_4">Example</A></H3>
6796 <PRE>
6797 #include &lt;cups/http.h&gt;
6798 #include &lt;cups/ipp.h&gt;
6799
6800 http_t *http;
6801
6802 http = httpConnect(cupsServer(), ippPort());
6803 </PRE>
6804 <H3><A NAME="10_80_5">See Also</A></H3>
6805 <A HREF="#cupsServer"> <CODE>cupsServer()</CODE></A>,<A HREF="#ippSetPort">
6806  <CODE>ippSetPort()</CODE></A>
6807 <!-- NEW PAGE -->
6808
6809 <H2><A NAME="ippRead">ippRead()</A></H2>
6810 <H3><A NAME="10_81_1">Usage</A></H3>
6811 <PRE>
6812 ipp_state_t ippRead(http_t *http, ipp_t *ipp);
6813 </PRE>
6814 <H3><A NAME="10_81_2">Arguments</A></H3>
6815 <CENTER>
6816 <TABLE BORDER WIDTH="80%">
6817 <TR><TH>Argument</TH><TH>Description</TH></TR>
6818 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6819 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6820 </TABLE>
6821 </CENTER>
6822 <H3><A NAME="10_81_3">Returns</A></H3>
6823 <P>The current read state.</P>
6824 <H3><A NAME="10_81_4">Description</A></H3>
6825 <P>The <CODE>ippRead()</CODE> function reads IPP attributes from the
6826  specified HTTP connection. Programs should continue calling <CODE>
6827 ippRead()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
6828  is returned.</P>
6829 <H3><A NAME="10_81_5">Example</A></H3>
6830 <PRE>
6831 #include &lt;cups/http.h&gt;
6832 #include &lt;cups/ipp.h&gt;
6833
6834 http_t *http;
6835 ipp_t *ipp;
6836 ipp_state_t status;
6837
6838 ipp = ippNew();
6839
6840 while ((status = ippRead(http, ipp)) != IPP_ERROR)
6841   if (status == IPP_DATA)
6842     break;
6843
6844 if (status == IPP_DATA)
6845 {
6846   ... read additional non-IPP data using httpRead() ...
6847 }
6848 </PRE>
6849 <H3><A NAME="10_81_6">See Also</A></H3>
6850 <A HREF="#ippWrite"> <CODE>ippWrite()</CODE></A>
6851 <!-- NEW PAGE -->
6852
6853 <H2><A NAME="ippSetPort">ippSetPort()</A></H2>
6854 <H3><A NAME="10_82_1">Usage</A></H3>
6855 <PRE>
6856 void
6857 ippSetPort(int port);
6858 </PRE>
6859 <H3><A NAME="10_82_2">Arguments</A></H3>
6860 <CENTER>
6861 <TABLE BORDER WIDTH="80%">
6862 <TR><TH>Argument</TH><TH>Description</TH></TR>
6863 <TR><TD>port</TD><TD>The port number to use</TD></TR>
6864 </TABLE>
6865 </CENTER>
6866 <H3><A NAME="10_82_3">Description</A></H3>
6867 <P>The <CODE>ippSetPort()</CODE> function sets the default IPP port
6868  number for requests.</P>
6869 <H3><A NAME="10_82_4">Example</A></H3>
6870 <PRE>
6871 #include &lt;cups/http.h&gt;
6872 #include &lt;cups/ipp.h&gt;
6873
6874 ...
6875
6876 ippSetPort(8631);
6877 </PRE>
6878 <H3><A NAME="10_82_5">See Also</A></H3>
6879 <A HREF="#ippPort"> <CODE>ippPort()</CODE></A>
6880 <!-- NEW PAGE -->
6881
6882 <H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
6883 <H3><A NAME="10_83_1">Usage</A></H3>
6884 <PRE>
6885 ipp_uchar_t *ippTimeToDate(time_t time);
6886 </PRE>
6887 <H3><A NAME="10_83_2">Arguments</A></H3>
6888 <CENTER>
6889 <TABLE BORDER WIDTH="80%">
6890 <TR><TH>Argument</TH><TH>Description</TH></TR>
6891 <TR><TD>time</TD><TD>The UNIX time value</TD></TR>
6892 </TABLE>
6893 </CENTER>
6894 <H3><A NAME="10_83_3">Returns</A></H3>
6895 <P>A static pointer to an IPP date-time value.</P>
6896 <H3><A NAME="10_83_4">Description</A></H3>
6897 <P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an
6898  IPP date-time value.</P>
6899 <H3><A NAME="10_83_5">Example</A></H3>
6900 <PRE>
6901 #include &lt;cups/ipp.h&gt;
6902
6903 ipp_uchar_t *date;
6904
6905 date = ippTimeToDate(time(NULL));
6906 </PRE>
6907 <H3><A NAME="10_83_6">See Also</A></H3>
6908 <A HREF="#ippDateToTime"> <CODE>ippDateToTime()</CODE></A>
6909 <!-- NEW PAGE -->
6910
6911 <H2><A NAME="ippWrite">ippWrite()</A></H2>
6912 <H3><A NAME="10_84_1">Usage</A></H3>
6913 <PRE>
6914 ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
6915 </PRE>
6916 <H3><A NAME="10_84_2">Arguments</A></H3>
6917 <CENTER>
6918 <TABLE BORDER WIDTH="80%">
6919 <TR><TH>Argument</TH><TH>Description</TH></TR>
6920 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6921 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6922 </TABLE>
6923 </CENTER>
6924 <H3><A NAME="10_84_3">Returns</A></H3>
6925 <P>The current write state.</P>
6926 <H3><A NAME="10_84_4">Description</A></H3>
6927 <P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the
6928  specified HTTP connection. Programs should continue calling <CODE>
6929 ippWrite()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
6930  is returned.</P>
6931 <H3><A NAME="10_84_5">Example</A></H3>
6932 <PRE>
6933 #include &lt;cups/http.h&gt;
6934 #include &lt;cups/ipp.h&gt;
6935
6936 http_t *http;
6937 ipp_t *ipp;
6938 ipp_state_t status;
6939
6940 ipp = ippNew();
6941 ... add attributes ...
6942
6943 while ((status = ippWrite(http, ipp)) != IPP_ERROR)
6944   if (status == IPP_DATA)
6945     break;
6946
6947 if (status == IPP_DATA)
6948 {
6949   ... read additional non-IPP data using httpWrite() ...
6950 }
6951 </PRE>
6952 <H3><A NAME="10_84_6">See Also</A></H3>
6953 <A HREF="#ippRead"> <CODE>ippRead()</CODE></A>
6954 <!-- NEW PAGE -->
6955
6956 <H2><A NAME="ppdClose">ppdClose()</A></H2>
6957 <H3><A NAME="10_85_1">Usage</A></H3>
6958 <PRE>
6959 void ppdClose(ppd_file_t *ppd);
6960 </PRE>
6961 <H3><A NAME="10_85_2">Arguments</A></H3>
6962 <CENTER>
6963 <TABLE BORDER WIDTH="80%">
6964 <TR><TH>Argument</TH><TH>Description</TH></TR>
6965 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
6966 </TABLE>
6967 </CENTER>
6968 <H3><A NAME="10_85_3">Description</A></H3>
6969 <P>The <CODE>ppdClose()</CODE> function frees all memory associated with
6970  the PPD file.</P>
6971 <H3><A NAME="10_85_4">Example</A></H3>
6972 <PRE>
6973 #include &lt;cups/ppd.h&gt;
6974
6975 ppd_file_t *ppd;
6976
6977 ppdClose(ppd);
6978 </PRE>
6979 <H3><A NAME="10_85_5">See Also</A></H3>
6980 <A HREF="#ppdOpen"> <CODE>ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
6981 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
6982 </A>
6983 <!-- NEW PAGE -->
6984
6985 <H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
6986 <H3><A NAME="10_86_1">Usage</A></H3>
6987 <PRE>
6988 int ppdConflicts(ppd_file_t *ppd);
6989 </PRE>
6990 <H3><A NAME="10_86_2">Arguments</A></H3>
6991 <CENTER>
6992 <TABLE BORDER WIDTH="80%">
6993 <TR><TH>Argument</TH><TH>Description</TH></TR>
6994 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
6995 </TABLE>
6996 </CENTER>
6997 <H3><A NAME="10_86_3">Returns</A></H3>
6998 <P>The number of option conflicts in the file.</P>
6999 <H3><A NAME="10_86_4">Description</A></H3>
7000 <P>The <CODE>ppdConflicts()</CODE> function returns the number of
7001  conflicts with the currently selected options.</P>
7002 <H3><A NAME="10_86_5">Example</A></H3>
7003 <PRE>
7004 #include &lt;cups/ppd.h&gt;
7005
7006 ppd_file_t *ppd;
7007
7008 printf(&quot;%d conflicts\n&quot;, ppdConflicts(ppd));
7009 </PRE>
7010 <H3><A NAME="10_86_6">See Also</A></H3>
7011 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdIsMarked">
7012  <CODE>ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7013 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7014 ppdMarkOption()</CODE></A>
7015 <!-- NEW PAGE -->
7016
7017 <H2><A NAME="ppdEmit">ppdEmit()</A></H2>
7018 <H3><A NAME="10_87_1">Usage</A></H3>
7019 <PRE>
7020 int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);
7021 </PRE>
7022 <H3><A NAME="10_87_2">Arguments</A></H3>
7023 <CENTER>
7024 <TABLE BORDER WIDTH="80%">
7025 <TR><TH>Argument</TH><TH>Description</TH></TR>
7026 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7027 <TR><TD>file</TD><TD>The file to write to</TD></TR>
7028 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7029 </TABLE>
7030 </CENTER>
7031 <H3><A NAME="10_87_3">Returns</A></H3>
7032 <P>0 on success, -1 on error.</P>
7033 <H3><A NAME="10_87_4">Description</A></H3>
7034 <P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
7035  commands to the specified file.</P>
7036 <H3><A NAME="10_87_5">Example</A></H3>
7037 <PRE>
7038 #include &lt;cups/ppd.h&gt;
7039
7040 ppd_file_t *ppd;
7041
7042 ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
7043 </PRE>
7044 <H3><A NAME="10_87_6">See Also</A></H3>
7045 <A HREF="#ppdEmitFd"> <CODE>ppdEmitFd()</CODE></A>
7046 <!-- NEW PAGE -->
7047
7048 <H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
7049 <H3><A NAME="10_88_1">Usage</A></H3>
7050 <PRE>
7051 int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);
7052 </PRE>
7053 <H3><A NAME="10_88_2">Arguments</A></H3>
7054 <CENTER>
7055 <TABLE BORDER WIDTH="80%">
7056 <TR><TH>Argument</TH><TH>Description</TH></TR>
7057 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7058 <TR><TD>fd</TD><TD>The file descriptor to write to</TD></TR>
7059 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7060 </TABLE>
7061 </CENTER>
7062 <H3><A NAME="10_88_3">Returns</A></H3>
7063 <P>0 on success, -1 on error.</P>
7064 <H3><A NAME="10_88_4">Description</A></H3>
7065 <P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
7066  commands to the specified file descriptor.</P>
7067 <H3><A NAME="10_88_5">Example</A></H3>
7068 <PRE>
7069 #include &lt;cups/ppd.h&gt;
7070
7071 ppd_file_t *ppd;
7072
7073 ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
7074 </PRE>
7075 <H3><A NAME="10_88_6">See Also</A></H3>
7076 <A HREF="#ppdEmit"> <CODE>ppdEmit()</CODE></A>
7077 <!-- NEW PAGE -->
7078
7079 <H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
7080 <H3><A NAME="10_89_1">Usage</A></H3>
7081 <PRE>
7082 ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);
7083 </PRE>
7084 <H3><A NAME="10_89_2">Arguments</A></H3>
7085 <CENTER>
7086 <TABLE BORDER WIDTH="80%">
7087 <TR><TH>Argument</TH><TH>Description</TH></TR>
7088 <TR><TD>option</TD><TD>A pointer to the option</TD></TR>
7089 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7090 </TABLE>
7091 </CENTER>
7092 <H3><A NAME="10_89_3">Returns</A></H3>
7093 <P>A pointer to the choice data or NULL if the choice does not exist.</P>
7094 <H3><A NAME="10_89_4">Description</A></H3>
7095 <P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the
7096  choice data for the specified option.</P>
7097 <H3><A NAME="10_89_5">Example</A></H3>
7098 <PRE>
7099 #include &lt;cups/ppd.h&gt;
7100
7101 ppd_file_t *ppd;
7102 ppd_option_t *option;
7103 ppd_choice_t *choice;
7104
7105 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7106 choice = ppdFindChoice(option, &quot;Letter&quot;);
7107 </PRE>
7108 <H3><A NAME="10_89_6">See Also</A></H3>
7109 <A HREF="#ppdFindMarkedChoice"> <CODE>ppdFindMarkedChoice()</CODE></A>,<A
7110 HREF="#ppdFindOption"> <CODE>ppdFindOption()</CODE></A>
7111 <!-- NEW PAGE -->
7112
7113 <H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
7114 <H3><A NAME="10_90_1">Usage</A></H3>
7115 <PRE>
7116 ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
7117 </PRE>
7118 <H3><A NAME="10_90_2">Arguments</A></H3>
7119 <CENTER>
7120 <TABLE BORDER WIDTH="80%">
7121 <TR><TH>Argument</TH><TH>Description</TH></TR>
7122 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7123 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7124 </TABLE>
7125 </CENTER>
7126 <H3><A NAME="10_90_3">Returns</A></H3>
7127 <P>A pointer to the choice data or NULL if the choice does not exist or
7128  is not marked.</P>
7129 <H3><A NAME="10_90_4">Description</A></H3>
7130 <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
7131  the marked choice data for the specified option.</P>
7132 <H3><A NAME="10_90_5">Example</A></H3>
7133 <PRE>
7134 #include &lt;cups/ppd.h&gt;
7135
7136 ppd_file_t *ppd;
7137 ppd_choice_t *choice;
7138
7139 choice = ppdFindMarkedChoice(ppd, &quot;PageSize&quot;);
7140 </PRE>
7141 <H3><A NAME="10_90_6">See Also</A></H3>
7142 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindOption">
7143  <CODE>ppdFindOption()</CODE></A>
7144 <!-- NEW PAGE -->
7145
7146 <H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
7147 <H3><A NAME="10_91_1">Usage</A></H3>
7148 <PRE>
7149 ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
7150 </PRE>
7151 <H3><A NAME="10_91_2">Arguments</A></H3>
7152 <CENTER>
7153 <TABLE BORDER WIDTH="80%">
7154 <TR><TH>Argument</TH><TH>Description</TH></TR>
7155 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7156 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7157 </TABLE>
7158 </CENTER>
7159 <H3><A NAME="10_91_3">Returns</A></H3>
7160 <P>A pointer to the option data or NULL if the option does not exist.</P>
7161 <H3><A NAME="10_91_4">Description</A></H3>
7162 <P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the
7163  option data for the specified option.</P>
7164 <H3><A NAME="10_91_5">Example</A></H3>
7165 <PRE>
7166 #include &lt;cups/ppd.h&gt;
7167
7168 ppd_file_t *ppd;
7169 ppd_option_t *option;
7170
7171 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7172 </PRE>
7173 <H3><A NAME="10_91_6">See Also</A></H3>
7174 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindMarkedChoice">
7175  <CODE>ppdFindMarkedChoice()</CODE></A>
7176 <!-- NEW PAGE -->
7177
7178 <H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
7179 <H3><A NAME="10_92_1">Usage</A></H3>
7180 <PRE>
7181 int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);
7182 </PRE>
7183 <H3><A NAME="10_92_2">Arguments</A></H3>
7184 <CENTER>
7185 <TABLE BORDER WIDTH="80%">
7186 <TR><TH>Argument</TH><TH>Description</TH></TR>
7187 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7188 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7189 <TR><TD>choice</TD><TD>The name of the option choice</TD></TR>
7190 </TABLE>
7191 </CENTER>
7192 <H3><A NAME="10_92_3">Returns</A></H3>
7193 <P>1 if the choice is marked, 0 otherwise.</P>
7194 <H3><A NAME="10_92_4">Description</A></H3>
7195 <P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
7196  specified option choice is marked.</P>
7197 <H3><A NAME="10_92_5">Example</A></H3>
7198 <PRE>
7199 #include &lt;cups/ppd.h&gt;
7200
7201 ppd_file_t *ppd;
7202
7203 printf(&quot;Letter size %s selected.\n&quot;,
7204        ppdIsMarked(ppd, &quot;PageSize&quot;, &quot;Letter&quot;) ? &quot;is&quot; : &quot;is not&quot;);
7205 </PRE>
7206 <H3><A NAME="10_92_6">See Also</A></H3>
7207 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7208  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7209 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7210 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7211 ppdMarkOption()</CODE></A>
7212 <!-- NEW PAGE -->
7213
7214 <H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
7215 <H3><A NAME="10_93_1">Usage</A></H3>
7216 <PRE>
7217 void ppdMarkDefaults(ppd_file_t *ppd);
7218 </PRE>
7219 <H3><A NAME="10_93_2">Arguments</A></H3>
7220 <CENTER>
7221 <TABLE BORDER WIDTH="80%">
7222 <TR><TH>Argument</TH><TH>Description</TH></TR>
7223 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7224 </TABLE>
7225 </CENTER>
7226 <H3><A NAME="10_93_3">Description</A></H3>
7227 <P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
7228  choices in the PPD file.</P>
7229 <H3><A NAME="10_93_4">Example</A></H3>
7230 <PRE>
7231 #include &lt;cups/ppd.h&gt;
7232
7233 ppd_file_t *ppd;
7234
7235 ppdMarkDefaults(ppd);
7236 </PRE>
7237 <H3><A NAME="10_93_5">See Also</A></H3>
7238 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7239  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7240 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7241 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7242 ppdMarkOption()</CODE></A>
7243 <!-- NEW PAGE -->
7244
7245 <H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
7246 <H3><A NAME="10_94_1">Usage</A></H3>
7247 <PRE>
7248 int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);
7249 </PRE>
7250 <H3><A NAME="10_94_2">Arguments</A></H3>
7251 <CENTER>
7252 <TABLE BORDER WIDTH="80%">
7253 <TR><TH>Argument</TH><TH>Description</TH></TR>
7254 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7255 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7256 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7257 </TABLE>
7258 </CENTER>
7259 <H3><A NAME="10_94_3">Returns</A></H3>
7260 <P>The number of conflicts in the PPD file.</P>
7261 <H3><A NAME="10_94_4">Description</A></H3>
7262 <P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
7263  choice.</P>
7264 <H3><A NAME="10_94_5">Example</A></H3>
7265 <PRE>
7266 #include &lt;cups/ppd.h&gt;
7267
7268 ppd_file_t *ppd;
7269
7270 ppdMarkOption(ppd, &quot;PageSize&quot;, &quot;Letter&quot;);
7271 </PRE>
7272 <H3><A NAME="10_94_6">See Also</A></H3>
7273 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7274  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7275 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7276 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7277 ppdMarkOption()</CODE></A>
7278 <!-- NEW PAGE -->
7279
7280 <H2><A NAME="ppdOpen">ppdOpen()</A></H2>
7281 <H3><A NAME="10_95_1">Usage</A></H3>
7282 <PRE>
7283 ppd_file_t *ppdOpen(FILE *file);
7284 </PRE>
7285 <H3><A NAME="10_95_2">Arguments</A></H3>
7286 <CENTER>
7287 <TABLE BORDER WIDTH="80%">
7288 <TR><TH>Argument</TH><TH>Description</TH></TR>
7289 <TR><TD>file</TD><TD>The file to read from</TD></TR>
7290 </TABLE>
7291 </CENTER>
7292 <H3><A NAME="10_95_3">Returns</A></H3>
7293 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7294  be read.</P>
7295 <H3><A NAME="10_95_4">Description</A></H3>
7296 <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the
7297  specified file into memory.</P>
7298 <H3><A NAME="10_95_5">Example</A></H3>
7299 <PRE>
7300 #include &lt;cups/ppd.h&gt;
7301
7302 ppd_file_t *ppd;
7303 FILE *file;
7304
7305 file = fopen(&quot;filename.ppd&quot;, &quot;rb&quot;);
7306 ppd = ppdOpen(file);
7307 fclose(file);
7308 </PRE>
7309 <H3><A NAME="10_95_6">See Also</A></H3>
7310 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
7311 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
7312 </A>
7313 <!-- NEW PAGE -->
7314
7315 <H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
7316 <H3><A NAME="10_96_1">Usage</A></H3>
7317 <PRE>
7318 ppd_file_t *ppdOpenFd(int fd);
7319 </PRE>
7320 <H3><A NAME="10_96_2">Arguments</A></H3>
7321 <CENTER>
7322 <TABLE BORDER WIDTH="80%">
7323 <TR><TH>Argument</TH><TH>Description</TH></TR>
7324 <TR><TD>fd</TD><TD>The file descriptor to read from</TD></TR>
7325 </TABLE>
7326 </CENTER>
7327 <H3><A NAME="10_96_3">Returns</A></H3>
7328 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7329  be read.</P>
7330 <H3><A NAME="10_96_4">Description</A></H3>
7331 <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the
7332  specified file descriptor into memory.</P>
7333 <H3><A NAME="10_96_5">Example</A></H3>
7334 <PRE>
7335 #include &lt;cups/ppd.h&gt;
7336
7337 ppd_file_t *ppd;
7338 int        fd;
7339
7340 fd = open(&quot;filename.ppd&quot;, O_RDONLY);
7341 ppd = ppdOpenFd(fd);
7342 close(fd);
7343 </PRE>
7344 <H3><A NAME="10_96_6">See Also</A></H3>
7345 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7346 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE></A>
7347 <!-- NEW PAGE -->
7348
7349 <H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
7350 <H3><A NAME="10_97_1">Usage</A></H3>
7351 <PRE>
7352 ppd_file_t *ppdOpenFile(const char *filename);
7353 </PRE>
7354 <H3><A NAME="10_97_2">Arguments</A></H3>
7355 <CENTER>
7356 <TABLE BORDER WIDTH="80%">
7357 <TR><TH>Argument</TH><TH>Description</TH></TR>
7358 <TR><TD>filename</TD><TD>The name of the file to read from</TD></TR>
7359 </TABLE>
7360 </CENTER>
7361 <H3><A NAME="10_97_3">Returns</A></H3>
7362 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7363  be read.</P>
7364 <H3><A NAME="10_97_4">Description</A></H3>
7365 <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the
7366  named file into memory.</P>
7367 <H3><A NAME="10_97_5">Example</A></H3>
7368 <PRE>
7369 #include &lt;cups/ppd.h&gt;
7370
7371 ppd_file_t *ppd;
7372
7373 ppd = ppdOpenFile(&quot;filename.ppd&quot;);
7374 </PRE>
7375 <H3><A NAME="10_97_6">See Also</A></H3>
7376 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7377 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>ppdOpenFd()</CODE></A>
7378 <!-- NEW PAGE -->
7379
7380 <H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
7381 <H3><A NAME="10_98_1">Usage</A></H3>
7382 <PRE>
7383 float ppdPageLength(ppd_file_t *ppd, const char *name);
7384 </PRE>
7385 <H3><A NAME="10_98_2">Arguments</A></H3>
7386 <CENTER>
7387 <TABLE BORDER WIDTH="80%">
7388 <TR><TH>Argument</TH><TH>Description</TH></TR>
7389 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7390 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7391 </TABLE>
7392 </CENTER>
7393 <H3><A NAME="10_98_3">Returns</A></H3>
7394 <P>The length of the specified page size in points or 0 if the page size
7395  does not exist.</P>
7396 <H3><A NAME="10_98_4">Description</A></H3>
7397 <P>The <CODE>ppdPageLength()</CODE> function returns the page length of
7398  the specified page size.</P>
7399 <H3><A NAME="10_98_5">Example</A></H3>
7400 <PRE>
7401 #include &lt;cups/ppd.h&gt;
7402
7403 ppd_file_t *ppd;
7404
7405 printf(&quot;Length = %.0f\n&quot;, ppdPageLength(ppd, &quot;Letter&quot;));
7406 </PRE>
7407 <H3><A NAME="10_98_6">See Also</A></H3>
7408 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7409  <CODE>ppdPageSize()</CODE></A>,<A HREF="#ppdPageWidth"> <CODE>
7410 ppdPageWidth()</CODE></A>
7411 <!-- NEW PAGE -->
7412
7413 <H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
7414 <H3><A NAME="10_99_1">Usage</A></H3>
7415 <PRE>
7416 ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
7417 </PRE>
7418 <H3><A NAME="10_99_2">Arguments</A></H3>
7419 <CENTER>
7420 <TABLE BORDER WIDTH="80%">
7421 <TR><TH>Argument</TH><TH>Description</TH></TR>
7422 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7423 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7424 </TABLE>
7425 </CENTER>
7426 <H3><A NAME="10_99_3">Returns</A></H3>
7427 <P>A pointer to the page size record of the specified page size in
7428  points or NULL if the page size does not exist.</P>
7429 <H3><A NAME="10_99_4">Description</A></H3>
7430 <P>The <CODE>ppdPageSize()</CODE> function returns the page size record
7431  for the specified page size.</P>
7432 <H3><A NAME="10_99_5">Example</A></H3>
7433 <PRE>
7434 #include &lt;cups/ppd.h&gt;
7435
7436 ppd_file_t *ppd;
7437 ppd_size_t *size;
7438
7439 size = ppdPageSize(ppd, &quot;Letter&quot;);
7440 if (size != NULL)
7441 {
7442   printf(&quot; Width = %.0f\n&quot;, size-&gt;width);
7443   printf(&quot;Length = %.0f\n&quot;, size-&gt;length);
7444   printf(&quot;  Left = %.0f\n&quot;, size-&gt;left);
7445   printf(&quot; Right = %.0f\n&quot;, size-&gt;right);
7446   printf(&quot;Bottom = %.0f\n&quot;, size-&gt;bottom);
7447   printf(&quot;   Top = %.0f\n&quot;, size-&gt;top);
7448 }
7449 </PRE>
7450 <H3><A NAME="10_99_6">See Also</A></H3>
7451 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageWidth">
7452  <CODE>ppdPageWidth()</CODE></A>
7453 <!-- NEW PAGE -->
7454
7455 <H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
7456 <H3><A NAME="10_100_1">Usage</A></H3>
7457 <PRE>
7458 float ppdPageWidth(ppd_file_t *ppd, const char *name);
7459 </PRE>
7460 <H3><A NAME="10_100_2">Arguments</A></H3>
7461 <CENTER>
7462 <TABLE BORDER WIDTH="80%">
7463 <TR><TH>Argument</TH><TH>Description</TH></TR>
7464 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7465 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7466 </TABLE>
7467 </CENTER>
7468 <H3><A NAME="10_100_3">Returns</A></H3>
7469 <P>The width of the specified page size in points or 0 if the page size
7470  does not exist.</P>
7471 <H3><A NAME="10_100_4">Description</A></H3>
7472 <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of
7473  the specified page size.</P>
7474 <H3><A NAME="10_100_5">Example</A></H3>
7475 <PRE>
7476 #include &lt;cups/ppd.h&gt;
7477
7478 ppd_file_t *ppd;
7479
7480 printf(&quot;Width = %.0f\n&quot;, ppdPageWidth(ppd, &quot;Letter&quot;));
7481 </PRE>
7482 <H3><A NAME="10_100_6">See Also</A></H3>
7483 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7484  <CODE>ppdPageSize()</CODE></A></BODY>
7485 </HTML>