doc/spm.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>CUPS Software Programmers Manual</TITLE>
   5 <META NAME="author" CONTENT="Easy Software Products">
   6 <META NAME="copyright" CONTENT="Copyright 1997-2002, All Rights Reserved">
   7 <META NAME="docnumber" CONTENT="CUPS-SPM-1.1.14">
   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.14<BR>
  26 Easy Software Products<BR>
  27 Copyright 1997-2002, All Rights Reserved<BR>
  28 </CENTER>
  29 <HR>
  30 <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1>
  31 <BR>
  32 <BR><B><A HREF="#1">Preface</A></B>
  33 <UL>
  34 <LI><A HREF="#1_1">System Overview</A></LI>
  35 <LI><A HREF="#1_2">Document Overview</A></LI>
  36 <LI><A HREF="#1_3">Notation Conventions</A></LI>
  37 <LI><A HREF="#1_4">Abbreviations</A></LI>
  38 <LI><A HREF="#1_5">Other References</A></LI>
  39 </UL>
  40 <B><A HREF="#OVERVIEW">1 - Printing System Overview</A></B>
  41 <UL>
  42 <LI><A HREF="#2_1">The Printing Problem</A></LI>
  43 <LI><A HREF="#2_2">The Technology</A></LI>
  44 <LI><A HREF="#2_3">Jobs</A></LI>
  45 <LI><A HREF="#2_4">Classes</A></LI>
  46 <LI><A HREF="#2_5">Filters</A></LI>
  47 <LI><A HREF="#2_6">Backends</A></LI>
  48 <LI><A HREF="#2_7">Printer Drivers</A></LI>
  49 <LI><A HREF="#2_8">Networking</A></LI>
  50 </UL>
  51 <B><A HREF="#CUPS_API">2 - The CUPS API</A></B>
  52 <UL>
  53 <LI><A HREF="#3_1">The CUPS API Library</A></LI>
  54 <UL>
  55 <LI><A HREF="#3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></LI>
  56 </UL>
  57 <LI><A HREF="#3_2">Printing Services</A></LI>
  58 <UL>
  59 <LI><A HREF="#3_2_1">Include Files</A></LI>
  60 <LI><A HREF="#3_2_2">Printing a File</A></LI>
  61 <LI><A HREF="#3_2_3">Printing Multiple Files</A></LI>
  62 <LI><A HREF="#3_2_4">Cancelling Jobs</A></LI>
  63 <LI><A HREF="#3_2_5">Getting the Available Printers and Classes</A></LI>
  64 <LI><A HREF="#3_2_6">Printing with Options</A></LI>
  65 <LI><A HREF="#3_2_7">Setting Printer Options</A></LI>
  66 <LI><A HREF="#3_2_8">Getting Errors</A></LI>
  67 <LI><A HREF="#3_2_9">Passwords and Authentication</A></LI>
  68 </UL>
  69 <LI><A HREF="#3_3">PPD Services</A></LI>
  70 <UL>
  71 <LI><A HREF="#3_3_1">Include Files</A></LI>
  72 <LI><A HREF="#3_3_2">Getting a PPD File for a Printer</A></LI>
  73 <LI><A HREF="#3_3_3">Loading a PPD File</A></LI>
  74 <LI><A HREF="#3_3_4">Freeing PPD File Information</A></LI>
  75 <LI><A HREF="#3_3_5">The PPD File Structure</A></LI>
  76 <LI><A HREF="#3_3_6">Marking Options</A></LI>
  77 <LI><A HREF="#3_3_7">Checking for Conflicts</A></LI>
  78 </UL>
  79 </UL>
  80 <B><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></B>
  81 <UL>
  82 <LI><A HREF="#4_1">Overview</A></LI>
  83 <UL>
  84 <LI><A HREF="#4_1_1">Security Considerations</A></LI>
  85 <LI><A HREF="#4_1_2">Users and Groups</A></LI>
  86 <LI><A HREF="#4_1_3">Temporary Files</A></LI>
  87 <LI><A HREF="#4_1_4">Sending Messages to the User</A></LI>
  88 <LI><A HREF="#4_1_5">Page Accounting</A></LI>
  89 <LI><A HREF="#4_1_6">Command-Line Arguments</A></LI>
  90 <LI><A HREF="#4_1_7">Copy Generation</A></LI>
  91 <LI><A HREF="#4_1_8">Environment Variables</A></LI>
  92 </UL>
  93 <LI><A HREF="#4_2">Dissecting the HP-GL/2 Filter</A></LI>
  94 <UL>
  95 <LI><A HREF="#4_2_1">Initializing the Filter</A></LI>
  96 </UL>
  97 <LI><A HREF="#4_3">PostScript Output</A></LI>
  98 </UL>
  99 <B><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></B>
 100 <UL>
 101 <LI><A HREF="#5_1">Overview</A></LI>
 102 <UL>
 103 <LI><A HREF="#5_1_1">CUPS Raster Data</A></LI>
 104 <LI><A HREF="#5_1_2">Page Accounting</A></LI>
 105 <LI><A HREF="#5_1_3">Color Management</A></LI>
 106 <LI><A HREF="#5_1_4">Device and Bitmap Variables</A></LI>
 107 </UL>
 108 <LI><A HREF="#5_2">Dissecting the HP-PCL Driver</A></LI>
 109 <UL>
 110 <LI><A HREF="#5_2_1">PPD Files</A></LI>
 111 <LI><A HREF="#5_2_2">Reading Raster Data</A></LI>
 112 </UL>
 113 </UL>
 114 <B><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></B>
 115 <UL>
 116 <LI><A HREF="#6_1">Overview</A></LI>
 117 <UL>
 118 <LI><A HREF="#6_1_1">Security Considerations</A></LI>
 119 <LI><A HREF="#6_1_2">Command-Line Arguments</A></LI>
 120 <LI><A HREF="#6_1_3">Copy Generation</A></LI>
 121 <LI><A HREF="#6_1_4">Page Accounting</A></LI>
 122 <LI><A HREF="#6_1_5">Exclusive Access</A></LI>
 123 <LI><A HREF="#6_1_6">Retries</A></LI>
 124 </UL>
 125 <LI><A HREF="#6_2">Dissecting the Serial Port Backend</A></LI>
 126 <UL>
 127 <LI><A HREF="#6_2_1">Supporting Device Discovery</A></LI>
 128 <LI><A HREF="#6_2_2">Opening the Serial Port</A></LI>
 129 <LI><A HREF="#6_2_3">Writing Data to the Port</A></LI>
 130 <LI><A HREF="#6_2_4">Finishing Up</A></LI>
 131 </UL>
 132 </UL>
 133 <B><A HREF="#LICENSE">A - Software License Agreement</A></B>
 134 <UL>
 135 <LI><A HREF="#7_1">Common UNIX Printing System License Agreement</A></LI>
 136 <UL>
 137 <LI><A HREF="#7_1_1">Introduction</A></LI>
 138 <LI><A HREF="#7_1_2">Apple Operating System Development License
 139  Exception</A></LI>
 140 <LI><A HREF="#7_1_3">Trademarks</A></LI>
 141 <LI><A HREF="#7_1_4">Binary Distribution Rights</A></LI>
 142 <LI><A HREF="#7_1_5">Support</A></LI>
 143 </UL>
 144 <LI><A HREF="#7_2">GNU GENERAL PUBLIC LICENSE</A></LI>
 145 <LI><A HREF="#7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></LI>
 146 </UL>
 147 <B><A HREF="#CONSTANTS">B - Constants</A></B>
 148 <UL>
 149 <LI><A HREF="#8_1">CUPS Constants</A></LI>
 150 <UL>
 151 <LI><A HREF="#8_1_1">Version Number</A></LI>
 152 <LI><A HREF="#8_1_2">Printer Capabilities</A></LI>
 153 <LI><A HREF="#8_1_3">Encodings</A></LI>
 154 </UL>
 155 <LI><A HREF="#8_2">HTTP Constants</A></LI>
 156 <UL>
 157 <LI><A HREF="#8_2_1">Limits</A></LI>
 158 <LI><A HREF="#8_2_2">Status Codes</A></LI>
 159 <LI><A HREF="#8_2_3">Fields</A></LI>
 160 </UL>
 161 <LI><A HREF="#8_3">IPP Constants</A></LI>
 162 <UL>
 163 <LI><A HREF="#8_3_1">Limits</A></LI>
 164 <LI><A HREF="#8_3_2">Tags</A></LI>
 165 <LI><A HREF="#8_3_3">Resolution Units</A></LI>
 166 <LI><A HREF="#8_3_4">Finishings</A></LI>
 167 <LI><A HREF="#8_3_5">Orientations</A></LI>
 168 <LI><A HREF="#8_3_6">Qualities</A></LI>
 169 <LI><A HREF="#8_3_7">Job States</A></LI>
 170 <LI><A HREF="#8_3_8">Printer States</A></LI>
 171 <LI><A HREF="#8_3_9">Operations</A></LI>
 172 <LI><A HREF="#8_3_10">Status Codes</A></LI>
 173 </UL>
 174 <LI><A HREF="#8_4">PPD Constants</A></LI>
 175 <UL>
 176 <LI><A HREF="#8_4_1">PPD Format Version</A></LI>
 177 <LI><A HREF="#8_4_2">PPD User-Interface Types</A></LI>
 178 <LI><A HREF="#8_4_3">PPD Sections</A></LI>
 179 <LI><A HREF="#8_4_4">PPD Colorspaces</A></LI>
 180 </UL>
 181 <LI><A HREF="#8_5">Raster Constants</A></LI>
 182 <UL>
 183 <LI><A HREF="#8_5_1">Raster Sync Words</A></LI>
 184 <LI><A HREF="#8_5_2">Raster Stream Modes</A></LI>
 185 <LI><A HREF="#8_5_3">Raster Boolean Constants</A></LI>
 186 <LI><A HREF="#8_5_4">Raster Jog Values</A></LI>
 187 <LI><A HREF="#8_5_5">Raster Orientation Values</A></LI>
 188 <LI><A HREF="#8_5_6">Raster CutMedia Values</A></LI>
 189 <LI><A HREF="#8_5_7">Raster AdvanceMedia Values</A></LI>
 190 <LI><A HREF="#8_5_8">Raster LeadingEdge Values</A></LI>
 191 <LI><A HREF="#8_5_9">Raster Color Order Values</A></LI>
 192 <LI><A HREF="#8_5_10">Raster Colorspace Values</A></LI>
 193 </UL>
 194 </UL>
 195 <B><A HREF="#STRUCTURES">C - Structures</A></B>
 196 <UL>
 197 <LI><A HREF="#9_1">CUPS Structures</A></LI>
 198 <UL>
 199 <LI><A HREF="#cups_dest_t">CUPS Destinations</A></LI>
 200 <LI><A HREF="#cups_job_t">CUPS Jobs</A></LI>
 201 <LI><A HREF="#cups_lang_t">CUPS Messages</A></LI>
 202 <LI><A HREF="#cups_option_t">CUPS Options</A></LI>
 203 </UL>
 204 <LI><A HREF="#9_2">Networking Structures</A></LI>
 205 <UL>
 206 <LI><A HREF="#http_t">HTTP State</A></LI>
 207 <LI><A HREF="#ipp_t">IPP State</A></LI>
 208 </UL>
 209 <LI><A HREF="#9_3">Raster Structures</A></LI>
 210 <UL>
 211 <LI><A HREF="#cups_raster_header_t">Raster Page Header</A></LI>
 212 </UL>
 213 </UL>
 214 <B><A HREF="#FUNCTIONS">D - Functions</A></B>
 215 <UL>
 216 <LI><A HREF="#cupsAddOption">cupsAddOption()</A></LI>
 217 <UL>
 218 <LI><A HREF="#10_1_1">Usage</A></LI>
 219 <LI><A HREF="#10_1_2">Arguments</A></LI>
 220 <LI><A HREF="#10_1_3">Returns</A></LI>
 221 <LI><A HREF="#10_1_4">Description</A></LI>
 222 <LI><A HREF="#10_1_5">Example</A></LI>
 223 <LI><A HREF="#10_1_6">See Also</A></LI>
 224 </UL>
 225 <LI><A HREF="#cupsCancelJob">cupsCancelJob()</A></LI>
 226 <UL>
 227 <LI><A HREF="#10_2_1">Usage</A></LI>
 228 <LI><A HREF="#10_2_2">Arguments</A></LI>
 229 <LI><A HREF="#10_2_3">Returns</A></LI>
 230 <LI><A HREF="#10_2_4">Description</A></LI>
 231 <LI><A HREF="#10_2_5">Example</A></LI>
 232 <LI><A HREF="#10_2_6">See Also</A></LI>
 233 </UL>
 234 <LI><A HREF="#cupsDoFileRequest">cupsDoFileRequest()</A></LI>
 235 <UL>
 236 <LI><A HREF="#10_3_1">Usage</A></LI>
 237 <LI><A HREF="#10_3_2">Arguments</A></LI>
 238 <LI><A HREF="#10_3_3">Returns</A></LI>
 239 <LI><A HREF="#10_3_4">Description</A></LI>
 240 <LI><A HREF="#10_3_5">Example</A></LI>
 241 <LI><A HREF="#10_3_6">See Also</A></LI>
 242 </UL>
 243 <LI><A HREF="#cupsDoRequest">cupsDoRequest()</A></LI>
 244 <UL>
 245 <LI><A HREF="#10_4_1">Usage</A></LI>
 246 <LI><A HREF="#10_4_2">Arguments</A></LI>
 247 <LI><A HREF="#10_4_3">Returns</A></LI>
 248 <LI><A HREF="#10_4_4">Description</A></LI>
 249 <LI><A HREF="#10_4_5">Example</A></LI>
 250 <LI><A HREF="#10_4_6">See Also</A></LI>
 251 </UL>
 252 <LI><A HREF="#cupsFreeOptions">cupsFreeOptions()</A></LI>
 253 <UL>
 254 <LI><A HREF="#10_5_1">Usage</A></LI>
 255 <LI><A HREF="#10_5_2">Arguments</A></LI>
 256 <LI><A HREF="#10_5_3">Description</A></LI>
 257 <LI><A HREF="#10_5_4">Example</A></LI>
 258 <LI><A HREF="#10_5_5">See Also</A></LI>
 259 </UL>
 260 <LI><A HREF="#cupsGetClasses">cupsGetClasses()</A></LI>
 261 <UL>
 262 <LI><A HREF="#10_6_1">Usage</A></LI>
 263 <LI><A HREF="#10_6_2">Arguments</A></LI>
 264 <LI><A HREF="#10_6_3">Returns</A></LI>
 265 <LI><A HREF="#10_6_4">Description</A></LI>
 266 <LI><A HREF="#10_6_5">Example</A></LI>
 267 <LI><A HREF="#10_6_6">See Also</A></LI>
 268 </UL>
 269 <LI><A HREF="#cupsGetDefault">cupsGetDefault()</A></LI>
 270 <UL>
 271 <LI><A HREF="#10_7_1">Usage</A></LI>
 272 <LI><A HREF="#10_7_2">Returns</A></LI>
 273 <LI><A HREF="#10_7_3">Description</A></LI>
 274 <LI><A HREF="#10_7_4">Example</A></LI>
 275 <LI><A HREF="#10_7_5">See Also</A></LI>
 276 </UL>
 277 <LI><A HREF="#cupsGetOption">cupsGetOption()</A></LI>
 278 <UL>
 279 <LI><A HREF="#10_8_1">Usage</A></LI>
 280 <LI><A HREF="#10_8_2">Arguments</A></LI>
 281 <LI><A HREF="#10_8_3">Returns</A></LI>
 282 <LI><A HREF="#10_8_4">Description</A></LI>
 283 <LI><A HREF="#10_8_5">See Also</A></LI>
 284 </UL>
 285 <LI><A HREF="#cupsGetPassword">cupsGetPassword()</A></LI>
 286 <UL>
 287 <LI><A HREF="#10_9_1">Usage</A></LI>
 288 <LI><A HREF="#10_9_2">Arguments</A></LI>
 289 <LI><A HREF="#10_9_3">Returns</A></LI>
 290 <LI><A HREF="#10_9_4">Description</A></LI>
 291 <LI><A HREF="#10_9_5">Example</A></LI>
 292 <LI><A HREF="#10_9_6">See Also</A></LI>
 293 </UL>
 294 <LI><A HREF="#cupsGetPPD">cupsGetPPD()</A></LI>
 295 <UL>
 296 <LI><A HREF="#10_10_1">Usage</A></LI>
 297 <LI><A HREF="#10_10_2">Arguments</A></LI>
 298 <LI><A HREF="#10_10_3">Returns</A></LI>
 299 <LI><A HREF="#10_10_4">Description</A></LI>
 300 <LI><A HREF="#10_10_5">Example</A></LI>
 301 </UL>
 302 <LI><A HREF="#cupsGetPrinters">cupsGetPrinters()</A></LI>
 303 <UL>
 304 <LI><A HREF="#10_11_1">Usage</A></LI>
 305 <LI><A HREF="#10_11_2">Arguments</A></LI>
 306 <LI><A HREF="#10_11_3">Returns</A></LI>
 307 <LI><A HREF="#10_11_4">Description</A></LI>
 308 <LI><A HREF="#10_11_5">Example</A></LI>
 309 <LI><A HREF="#10_11_6">See Also</A></LI>
 310 </UL>
 311 <LI><A HREF="#cupsLangDefault">cupsLangDefault()</A></LI>
 312 <UL>
 313 <LI><A HREF="#10_12_1">Usage</A></LI>
 314 <LI><A HREF="#10_12_2">Returns</A></LI>
 315 <LI><A HREF="#10_12_3">Description</A></LI>
 316 <LI><A HREF="#10_12_4">Example</A></LI>
 317 <LI><A HREF="#10_12_5">See Also</A></LI>
 318 </UL>
 319 <LI><A HREF="#cupsLangEncoding">cupsLangEncoding()</A></LI>
 320 <UL>
 321 <LI><A HREF="#10_13_1">Usage</A></LI>
 322 <LI><A HREF="#10_13_2">Arguments</A></LI>
 323 <LI><A HREF="#10_13_3">Returns</A></LI>
 324 <LI><A HREF="#10_13_4">Description</A></LI>
 325 <LI><A HREF="#10_13_5">Example</A></LI>
 326 <LI><A HREF="#10_13_6">See Also</A></LI>
 327 </UL>
 328 <LI><A HREF="#cupsLangFlush">cupsLangFlush()</A></LI>
 329 <UL>
 330 <LI><A HREF="#10_14_1">Usage</A></LI>
 331 <LI><A HREF="#10_14_2">Description</A></LI>
 332 <LI><A HREF="#10_14_3">Example</A></LI>
 333 <LI><A HREF="#10_14_4">See Also</A></LI>
 334 </UL>
 335 <LI><A HREF="#cupsLangFree">cupsLangFree()</A></LI>
 336 <UL>
 337 <LI><A HREF="#10_15_1">Usage</A></LI>
 338 <LI><A HREF="#10_15_2">Arguments</A></LI>
 339 <LI><A HREF="#10_15_3">Description</A></LI>
 340 <LI><A HREF="#10_15_4">Example</A></LI>
 341 <LI><A HREF="#10_15_5">See Also</A></LI>
 342 </UL>
 343 <LI><A HREF="#cupsLangGet">cupsLangGet()</A></LI>
 344 <UL>
 345 <LI><A HREF="#10_16_1">Usage</A></LI>
 346 <LI><A HREF="#10_16_2">Arguments</A></LI>
 347 <LI><A HREF="#10_16_3">Returns</A></LI>
 348 <LI><A HREF="#10_16_4">Description</A></LI>
 349 <LI><A HREF="#10_16_5">Example</A></LI>
 350 <LI><A HREF="#10_16_6">See Also</A></LI>
 351 </UL>
 352 <LI><A HREF="#cupsLangString">cupsLangString()</A></LI>
 353 <UL>
 354 <LI><A HREF="#10_17_1">Usage</A></LI>
 355 <LI><A HREF="#10_17_2">Arguments</A></LI>
 356 <LI><A HREF="#10_17_3">Returns</A></LI>
 357 <LI><A HREF="#10_17_4">Description</A></LI>
 358 <LI><A HREF="#10_17_5">Example</A></LI>
 359 <LI><A HREF="#10_17_6">See Also</A></LI>
 360 </UL>
 361 <LI><A HREF="#cupsLastError">cupsLastError()</A></LI>
 362 <UL>
 363 <LI><A HREF="#10_18_1">Usage</A></LI>
 364 <LI><A HREF="#10_18_2">Returns</A></LI>
 365 <LI><A HREF="#10_18_3">Description</A></LI>
 366 <LI><A HREF="#10_18_4">Example</A></LI>
 367 <LI><A HREF="#10_18_5">See Also</A></LI>
 368 </UL>
 369 <LI><A HREF="#cupsMarkOptions">cupsMarkOptions()</A></LI>
 370 <UL>
 371 <LI><A HREF="#10_19_1">Usage</A></LI>
 372 <LI><A HREF="#10_19_2">Arguments</A></LI>
 373 <LI><A HREF="#10_19_3">Returns</A></LI>
 374 <LI><A HREF="#10_19_4">Description</A></LI>
 375 <LI><A HREF="#10_19_5">Example</A></LI>
 376 <LI><A HREF="#10_19_6">See Also</A></LI>
 377 </UL>
 378 <LI><A HREF="#cupsParseOptions">cupsParseOptions()</A></LI>
 379 <UL>
 380 <LI><A HREF="#10_20_1">Usage</A></LI>
 381 <LI><A HREF="#10_20_2">Arguments</A></LI>
 382 <LI><A HREF="#10_20_3">Returns</A></LI>
 383 <LI><A HREF="#10_20_4">Description</A></LI>
 384 <LI><A HREF="#10_20_5">Example</A></LI>
 385 <LI><A HREF="#10_20_6">See Also</A></LI>
 386 </UL>
 387 <LI><A HREF="#cupsPrintFile">cupsPrintFile()</A></LI>
 388 <UL>
 389 <LI><A HREF="#10_21_1">Usage</A></LI>
 390 <LI><A HREF="#10_21_2">Arguments</A></LI>
 391 <LI><A HREF="#10_21_3">Returns</A></LI>
 392 <LI><A HREF="#10_21_4">Description</A></LI>
 393 <LI><A HREF="#10_21_5">Example</A></LI>
 394 <LI><A HREF="#10_21_6">See Also</A></LI>
 395 </UL>
 396 <LI><A HREF="#cupsPrintFiles">cupsPrintFiles()</A></LI>
 397 <UL>
 398 <LI><A HREF="#10_22_1">Usage</A></LI>
 399 <LI><A HREF="#10_22_2">Arguments</A></LI>
 400 <LI><A HREF="#10_22_3">Returns</A></LI>
 401 <LI><A HREF="#10_22_4">Description</A></LI>
 402 <LI><A HREF="#10_22_5">Example</A></LI>
 403 <LI><A HREF="#10_22_6">See Also</A></LI>
 404 </UL>
 405 <LI><A HREF="#cupsRasterClose">cupsRasterClose()</A></LI>
 406 <UL>
 407 <LI><A HREF="#10_23_1">Usage</A></LI>
 408 <LI><A HREF="#10_23_2">Arguments</A></LI>
 409 <LI><A HREF="#10_23_3">Description</A></LI>
 410 <LI><A HREF="#10_23_4">Example</A></LI>
 411 <LI><A HREF="#10_23_5">See Also</A></LI>
 412 </UL>
 413 <LI><A HREF="#cupsRasterOpen">cupsRasterOpen()</A></LI>
 414 <UL>
 415 <LI><A HREF="#10_24_1">Usage</A></LI>
 416 <LI><A HREF="#10_24_2">Arguments</A></LI>
 417 <LI><A HREF="#10_24_3">Returns</A></LI>
 418 <LI><A HREF="#10_24_4">Description</A></LI>
 419 <LI><A HREF="#10_24_5">Example</A></LI>
 420 <LI><A HREF="#10_24_6">See Also</A></LI>
 421 </UL>
 422 <LI><A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A></LI>
 423 <UL>
 424 <LI><A HREF="#10_25_1">Usage</A></LI>
 425 <LI><A HREF="#10_25_2">Arguments</A></LI>
 426 <LI><A HREF="#10_25_3">Returns</A></LI>
 427 <LI><A HREF="#10_25_4">Description</A></LI>
 428 <LI><A HREF="#10_25_5">Example</A></LI>
 429 <LI><A HREF="#10_25_6">See Also</A></LI>
 430 </UL>
 431 <LI><A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A></LI>
 432 <UL>
 433 <LI><A HREF="#10_26_1">Usage</A></LI>
 434 <LI><A HREF="#10_26_2">Arguments</A></LI>
 435 <LI><A HREF="#10_26_3">Returns</A></LI>
 436 <LI><A HREF="#10_26_4">Description</A></LI>
 437 <LI><A HREF="#10_26_5">Example</A></LI>
 438 <LI><A HREF="#10_26_6">See Also</A></LI>
 439 </UL>
 440 <LI><A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A></LI>
 441 <UL>
 442 <LI><A HREF="#10_27_1">Usage</A></LI>
 443 <LI><A HREF="#10_27_2">Arguments</A></LI>
 444 <LI><A HREF="#10_27_3">Returns</A></LI>
 445 <LI><A HREF="#10_27_4">Description</A></LI>
 446 <LI><A HREF="#10_27_5">Example</A></LI>
 447 <LI><A HREF="#10_27_6">See Also</A></LI>
 448 </UL>
 449 <LI><A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A></LI>
 450 <UL>
 451 <LI><A HREF="#10_28_1">Usage</A></LI>
 452 <LI><A HREF="#10_28_2">Arguments</A></LI>
 453 <LI><A HREF="#10_28_3">Returns</A></LI>
 454 <LI><A HREF="#10_28_4">Description</A></LI>
 455 <LI><A HREF="#10_28_5">Example</A></LI>
 456 <LI><A HREF="#10_28_6">See Also</A></LI>
 457 </UL>
 458 <LI><A HREF="#cupsServer">cupsServer()</A></LI>
 459 <UL>
 460 <LI><A HREF="#10_29_1">Usage</A></LI>
 461 <LI><A HREF="#10_29_2">Returns</A></LI>
 462 <LI><A HREF="#10_29_3">Description</A></LI>
 463 <LI><A HREF="#10_29_4">Example</A></LI>
 464 <LI><A HREF="#10_29_5">See Also</A></LI>
 465 </UL>
 466 <LI><A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A></LI>
 467 <UL>
 468 <LI><A HREF="#10_30_1">Usage</A></LI>
 469 <LI><A HREF="#10_30_2">Arguments</A></LI>
 470 <LI><A HREF="#10_30_3">Description</A></LI>
 471 <LI><A HREF="#10_30_4">Example</A></LI>
 472 <LI><A HREF="#10_30_5">See Also</A></LI>
 473 </UL>
 474 <LI><A HREF="#cupsSetServer">cupsSetServer()</A></LI>
 475 <UL>
 476 <LI><A HREF="#10_31_1">Usage</A></LI>
 477 <LI><A HREF="#10_31_2">Arguments</A></LI>
 478 <LI><A HREF="#10_31_3">Description</A></LI>
 479 <LI><A HREF="#10_31_4">Example</A></LI>
 480 <LI><A HREF="#10_31_5">See Also</A></LI>
 481 </UL>
 482 <LI><A HREF="#cupsSetUser">cupsSetUser()</A></LI>
 483 <UL>
 484 <LI><A HREF="#10_32_1">Usage</A></LI>
 485 <LI><A HREF="#10_32_2">Arguments</A></LI>
 486 <LI><A HREF="#10_32_3">Description</A></LI>
 487 <LI><A HREF="#10_32_4">Example</A></LI>
 488 <LI><A HREF="#10_32_5">See Also</A></LI>
 489 </UL>
 490 <LI><A HREF="#cupsTempFile">cupsTempFile()</A></LI>
 491 <UL>
 492 <LI><A HREF="#10_33_1">Usage</A></LI>
 493 <LI><A HREF="#10_33_2">Arguments</A></LI>
 494 <LI><A HREF="#10_33_3">Returns</A></LI>
 495 <LI><A HREF="#10_33_4">Description</A></LI>
 496 <LI><A HREF="#10_33_5">Example</A></LI>
 497 </UL>
 498 <LI><A HREF="#cupsUser">cupsUser()</A></LI>
 499 <UL>
 500 <LI><A HREF="#10_34_1">Usage</A></LI>
 501 <LI><A HREF="#10_34_2">Returns</A></LI>
 502 <LI><A HREF="#10_34_3">Description</A></LI>
 503 <LI><A HREF="#10_34_4">Example</A></LI>
 504 <LI><A HREF="#10_34_5">See Also</A></LI>
 505 </UL>
 506 <LI><A HREF="#httpBlocking">httpBlocking()</A></LI>
 507 <UL>
 508 <LI><A HREF="#10_35_1">Usage</A></LI>
 509 <LI><A HREF="#10_35_2">Arguments</A></LI>
 510 <LI><A HREF="#10_35_3">Description</A></LI>
 511 <LI><A HREF="#10_35_4">Example</A></LI>
 512 <LI><A HREF="#10_35_5">See Also</A></LI>
 513 </UL>
 514 <LI><A HREF="#httpCheck">httpCheck()</A></LI>
 515 <UL>
 516 <LI><A HREF="#10_36_1">Usage</A></LI>
 517 <LI><A HREF="#10_36_2">Arguments</A></LI>
 518 <LI><A HREF="#10_36_3">Returns</A></LI>
 519 <LI><A HREF="#10_36_4">Description</A></LI>
 520 <LI><A HREF="#10_36_5">Example</A></LI>
 521 <LI><A HREF="#10_36_6">See Also</A></LI>
 522 </UL>
 523 <LI><A HREF="#httpClearFields">httpClearFields()</A></LI>
 524 <UL>
 525 <LI><A HREF="#10_37_1">Usage</A></LI>
 526 <LI><A HREF="#10_37_2">Arguments</A></LI>
 527 <LI><A HREF="#10_37_3">Description</A></LI>
 528 <LI><A HREF="#10_37_4">Example</A></LI>
 529 <LI><A HREF="#10_37_5">See Also</A></LI>
 530 </UL>
 531 <LI><A HREF="#httpClose">httpClose()</A></LI>
 532 <UL>
 533 <LI><A HREF="#10_38_1">Usage</A></LI>
 534 <LI><A HREF="#10_38_2">Arguments</A></LI>
 535 <LI><A HREF="#10_38_3">Description</A></LI>
 536 <LI><A HREF="#10_38_4">Example</A></LI>
 537 <LI><A HREF="#10_38_5">See Also</A></LI>
 538 </UL>
 539 <LI><A HREF="#httpConnect">httpConnect()</A></LI>
 540 <UL>
 541 <LI><A HREF="#10_39_1">Usage</A></LI>
 542 <LI><A HREF="#10_39_2">Arguments</A></LI>
 543 <LI><A HREF="#10_39_3">Returns</A></LI>
 544 <LI><A HREF="#10_39_4">Description</A></LI>
 545 <LI><A HREF="#10_39_5">Example</A></LI>
 546 <LI><A HREF="#10_39_6">See Also</A></LI>
 547 </UL>
 548 <LI><A HREF="#httpDecode64">httpDecode64()</A></LI>
 549 <UL>
 550 <LI><A HREF="#10_40_1">Usage</A></LI>
 551 <LI><A HREF="#10_40_2">Arguments</A></LI>
 552 <LI><A HREF="#10_40_3">Returns</A></LI>
 553 <LI><A HREF="#10_40_4">Description</A></LI>
 554 <LI><A HREF="#10_40_5">Example</A></LI>
 555 <LI><A HREF="#10_40_6">See Also</A></LI>
 556 </UL>
 557 <LI><A HREF="#httpDelete">httpDelete()</A></LI>
 558 <UL>
 559 <LI><A HREF="#10_41_1">Usage</A></LI>
 560 <LI><A HREF="#10_41_2">Arguments</A></LI>
 561 <LI><A HREF="#10_41_3">Returns</A></LI>
 562 <LI><A HREF="#10_41_4">Description</A></LI>
 563 <LI><A HREF="#10_41_5">Example</A></LI>
 564 <LI><A HREF="#10_41_6">See Also</A></LI>
 565 </UL>
 566 <LI><A HREF="#httpEncode64">httpEncode64()</A></LI>
 567 <UL>
 568 <LI><A HREF="#10_42_1">Usage</A></LI>
 569 <LI><A HREF="#10_42_2">Arguments</A></LI>
 570 <LI><A HREF="#10_42_3">Returns</A></LI>
 571 <LI><A HREF="#10_42_4">Description</A></LI>
 572 <LI><A HREF="#10_42_5">Example</A></LI>
 573 <LI><A HREF="#10_42_6">See Also</A></LI>
 574 </UL>
 575 <LI><A HREF="#httpError">httpError()</A></LI>
 576 <UL>
 577 <LI><A HREF="#10_43_1">Usage</A></LI>
 578 <LI><A HREF="#10_43_2">Arguments</A></LI>
 579 <LI><A HREF="#10_43_3">Returns</A></LI>
 580 <LI><A HREF="#10_43_4">Description</A></LI>
 581 <LI><A HREF="#10_43_5">Example</A></LI>
 582 <LI><A HREF="#10_43_6">See Also</A></LI>
 583 </UL>
 584 <LI><A HREF="#httpFlush">httpFlush()</A></LI>
 585 <UL>
 586 <LI><A HREF="#10_44_1">Usage</A></LI>
 587 <LI><A HREF="#10_44_2">Arguments</A></LI>
 588 <LI><A HREF="#10_44_3">Description</A></LI>
 589 <LI><A HREF="#10_44_4">Example</A></LI>
 590 <LI><A HREF="#10_44_5">See Also</A></LI>
 591 </UL>
 592 <LI><A HREF="#httpGet">httpGet()</A></LI>
 593 <UL>
 594 <LI><A HREF="#10_45_1">Usage</A></LI>
 595 <LI><A HREF="#10_45_2">Arguments</A></LI>
 596 <LI><A HREF="#10_45_3">Returns</A></LI>
 597 <LI><A HREF="#10_45_4">Description</A></LI>
 598 <LI><A HREF="#10_45_5">Example</A></LI>
 599 <LI><A HREF="#10_45_6">See Also</A></LI>
 600 </UL>
 601 <LI><A HREF="#httpGets">httpGets()</A></LI>
 602 <UL>
 603 <LI><A HREF="#10_46_1">Usage</A></LI>
 604 <LI><A HREF="#10_46_2">Arguments</A></LI>
 605 <LI><A HREF="#10_46_3">Returns</A></LI>
 606 <LI><A HREF="#10_46_4">Description</A></LI>
 607 <LI><A HREF="#10_46_5">Example</A></LI>
 608 <LI><A HREF="#10_46_6">See Also</A></LI>
 609 </UL>
 610 <LI><A HREF="#httpGetDateString">httpGetDateString()</A></LI>
 611 <UL>
 612 <LI><A HREF="#10_47_1">Usage</A></LI>
 613 <LI><A HREF="#10_47_2">Arguments</A></LI>
 614 <LI><A HREF="#10_47_3">Returns</A></LI>
 615 <LI><A HREF="#10_47_4">Description</A></LI>
 616 <LI><A HREF="#10_47_5">Example</A></LI>
 617 <LI><A HREF="#10_47_6">See Also</A></LI>
 618 </UL>
 619 <LI><A HREF="#httpGetDateTime">httpGetDateTime()</A></LI>
 620 <UL>
 621 <LI><A HREF="#10_48_1">Usage</A></LI>
 622 <LI><A HREF="#10_48_2">Arguments</A></LI>
 623 <LI><A HREF="#10_48_3">Returns</A></LI>
 624 <LI><A HREF="#10_48_4">Description</A></LI>
 625 <LI><A HREF="#10_48_5">Example</A></LI>
 626 <LI><A HREF="#10_48_6">See Also</A></LI>
 627 </UL>
 628 <LI><A HREF="#httpGetField">httpGetField()</A></LI>
 629 <UL>
 630 <LI><A HREF="#10_49_1">Usage</A></LI>
 631 <LI><A HREF="#10_49_2">Arguments</A></LI>
 632 <LI><A HREF="#10_49_3">Returns</A></LI>
 633 <LI><A HREF="#10_49_4">Description</A></LI>
 634 <LI><A HREF="#10_49_5">Example</A></LI>
 635 <LI><A HREF="#10_49_6">See Also</A></LI>
 636 </UL>
 637 <LI><A HREF="#httpHead">httpHead()</A></LI>
 638 <UL>
 639 <LI><A HREF="#10_50_1">Usage</A></LI>
 640 <LI><A HREF="#10_50_2">Arguments</A></LI>
 641 <LI><A HREF="#10_50_3">Returns</A></LI>
 642 <LI><A HREF="#10_50_4">Description</A></LI>
 643 <LI><A HREF="#10_50_5">Example</A></LI>
 644 <LI><A HREF="#10_50_6">See Also</A></LI>
 645 </UL>
 646 <LI><A HREF="#httpInitialize">httpInitialize()</A></LI>
 647 <UL>
 648 <LI><A HREF="#10_51_1">Usage</A></LI>
 649 <LI><A HREF="#10_51_2">Description</A></LI>
 650 <LI><A HREF="#10_51_3">Example</A></LI>
 651 <LI><A HREF="#10_51_4">See Also</A></LI>
 652 </UL>
 653 <LI><A HREF="#httpOptions">httpOptions()</A></LI>
 654 <UL>
 655 <LI><A HREF="#10_52_1">Usage</A></LI>
 656 <LI><A HREF="#10_52_2">Arguments</A></LI>
 657 <LI><A HREF="#10_52_3">Returns</A></LI>
 658 <LI><A HREF="#10_52_4">Description</A></LI>
 659 <LI><A HREF="#10_52_5">Example</A></LI>
 660 <LI><A HREF="#10_52_6">See Also</A></LI>
 661 </UL>
 662 <LI><A HREF="#httpPost">httpPost()</A></LI>
 663 <UL>
 664 <LI><A HREF="#10_53_1">Usage</A></LI>
 665 <LI><A HREF="#10_53_2">Arguments</A></LI>
 666 <LI><A HREF="#10_53_3">Returns</A></LI>
 667 <LI><A HREF="#10_53_4">Description</A></LI>
 668 <LI><A HREF="#10_53_5">Example</A></LI>
 669 <LI><A HREF="#10_53_6">See Also</A></LI>
 670 </UL>
 671 <LI><A HREF="#httpPrintf">httpPrintf()</A></LI>
 672 <UL>
 673 <LI><A HREF="#10_54_1">Usage</A></LI>
 674 <LI><A HREF="#10_54_2">Arguments</A></LI>
 675 <LI><A HREF="#10_54_3">Returns</A></LI>
 676 <LI><A HREF="#10_54_4">Description</A></LI>
 677 <LI><A HREF="#10_54_5">Example</A></LI>
 678 <LI><A HREF="#10_54_6">See Also</A></LI>
 679 </UL>
 680 <LI><A HREF="#httpPut">httpPut()</A></LI>
 681 <UL>
 682 <LI><A HREF="#10_55_1">Usage</A></LI>
 683 <LI><A HREF="#10_55_2">Arguments</A></LI>
 684 <LI><A HREF="#10_55_3">Returns</A></LI>
 685 <LI><A HREF="#10_55_4">Description</A></LI>
 686 <LI><A HREF="#10_55_5">Example</A></LI>
 687 <LI><A HREF="#10_55_6">See Also</A></LI>
 688 </UL>
 689 <LI><A HREF="#httpRead">httpRead()</A></LI>
 690 <UL>
 691 <LI><A HREF="#10_56_1">Usage</A></LI>
 692 <LI><A HREF="#10_56_2">Arguments</A></LI>
 693 <LI><A HREF="#10_56_3">Returns</A></LI>
 694 <LI><A HREF="#10_56_4">Description</A></LI>
 695 <LI><A HREF="#10_56_5">Example</A></LI>
 696 <LI><A HREF="#10_56_6">See Also</A></LI>
 697 </UL>
 698 <LI><A HREF="#httpReconnect">httpReconnect()</A></LI>
 699 <UL>
 700 <LI><A HREF="#10_57_1">Usage</A></LI>
 701 <LI><A HREF="#10_57_2">Arguments</A></LI>
 702 <LI><A HREF="#10_57_3">Returns</A></LI>
 703 <LI><A HREF="#10_57_4">Description</A></LI>
 704 <LI><A HREF="#10_57_5">Example</A></LI>
 705 <LI><A HREF="#10_57_6">See Also</A></LI>
 706 </UL>
 707 <LI><A HREF="#httpSeparate">httpSeparate()</A></LI>
 708 <UL>
 709 <LI><A HREF="#10_58_1">Usage</A></LI>
 710 <LI><A HREF="#10_58_2">Arguments</A></LI>
 711 <LI><A HREF="#10_58_3">Description</A></LI>
 712 <LI><A HREF="#10_58_4">Example</A></LI>
 713 <LI><A HREF="#10_58_5">See Also</A></LI>
 714 </UL>
 715 <LI><A HREF="#httpSetField">httpSetField()</A></LI>
 716 <UL>
 717 <LI><A HREF="#10_59_1">Usage</A></LI>
 718 <LI><A HREF="#10_59_2">Arguments</A></LI>
 719 <LI><A HREF="#10_59_3">Description</A></LI>
 720 <LI><A HREF="#10_59_4">Example</A></LI>
 721 <LI><A HREF="#10_59_5">See Also</A></LI>
 722 </UL>
 723 <LI><A HREF="#httpTrace">httpTrace()</A></LI>
 724 <UL>
 725 <LI><A HREF="#10_60_1">Usage</A></LI>
 726 <LI><A HREF="#10_60_2">Arguments</A></LI>
 727 <LI><A HREF="#10_60_3">Returns</A></LI>
 728 <LI><A HREF="#10_60_4">Description</A></LI>
 729 <LI><A HREF="#10_60_5">Example</A></LI>
 730 <LI><A HREF="#10_60_6">See Also</A></LI>
 731 </UL>
 732 <LI><A HREF="#httpUpdate">httpUpdate()</A></LI>
 733 <UL>
 734 <LI><A HREF="#10_61_1">Usage</A></LI>
 735 <LI><A HREF="#10_61_2">Arguments</A></LI>
 736 <LI><A HREF="#10_61_3">Returns</A></LI>
 737 <LI><A HREF="#10_61_4">Description</A></LI>
 738 <LI><A HREF="#10_61_5">Example</A></LI>
 739 <LI><A HREF="#10_61_6">See Also</A></LI>
 740 </UL>
 741 <LI><A HREF="#httpWrite">httpWrite()</A></LI>
 742 <UL>
 743 <LI><A HREF="#10_62_1">Usage</A></LI>
 744 <LI><A HREF="#10_62_2">Arguments</A></LI>
 745 <LI><A HREF="#10_62_3">Returns</A></LI>
 746 <LI><A HREF="#10_62_4">Description</A></LI>
 747 <LI><A HREF="#10_62_5">Example</A></LI>
 748 <LI><A HREF="#10_62_6">See Also</A></LI>
 749 </UL>
 750 <LI><A HREF="#ippAddBoolean">ippAddBoolean()</A></LI>
 751 <UL>
 752 <LI><A HREF="#10_63_1">Usage</A></LI>
 753 <LI><A HREF="#10_63_2">Arguments</A></LI>
 754 <LI><A HREF="#10_63_3">Returns</A></LI>
 755 <LI><A HREF="#10_63_4">Description</A></LI>
 756 <LI><A HREF="#10_63_5">Example</A></LI>
 757 <LI><A HREF="#10_63_6">See Also</A></LI>
 758 </UL>
 759 <LI><A HREF="#ippAddBooleans">ippAddBooleans()</A></LI>
 760 <UL>
 761 <LI><A HREF="#10_64_1">Usage</A></LI>
 762 <LI><A HREF="#10_64_2">Arguments</A></LI>
 763 <LI><A HREF="#10_64_3">Returns</A></LI>
 764 <LI><A HREF="#10_64_4">Description</A></LI>
 765 <LI><A HREF="#10_64_5">Example</A></LI>
 766 <LI><A HREF="#10_64_6">See Also</A></LI>
 767 </UL>
 768 <LI><A HREF="#ippAddDate">ippAddDate()</A></LI>
 769 <UL>
 770 <LI><A HREF="#10_65_1">Usage</A></LI>
 771 <LI><A HREF="#10_65_2">Arguments</A></LI>
 772 <LI><A HREF="#10_65_3">Returns</A></LI>
 773 <LI><A HREF="#10_65_4">Description</A></LI>
 774 <LI><A HREF="#10_65_5">Example</A></LI>
 775 <LI><A HREF="#10_65_6">See Also</A></LI>
 776 </UL>
 777 <LI><A HREF="#ippAddInteger">ippAddInteger()</A></LI>
 778 <UL>
 779 <LI><A HREF="#10_66_1">Usage</A></LI>
 780 <LI><A HREF="#10_66_2">Arguments</A></LI>
 781 <LI><A HREF="#10_66_3">Returns</A></LI>
 782 <LI><A HREF="#10_66_4">Description</A></LI>
 783 <LI><A HREF="#10_66_5">Example</A></LI>
 784 <LI><A HREF="#10_66_6">See Also</A></LI>
 785 </UL>
 786 <LI><A HREF="#ippAddIntegers">ippAddIntegers()</A></LI>
 787 <UL>
 788 <LI><A HREF="#10_67_1">Usage</A></LI>
 789 <LI><A HREF="#10_67_2">Arguments</A></LI>
 790 <LI><A HREF="#10_67_3">Returns</A></LI>
 791 <LI><A HREF="#10_67_4">Description</A></LI>
 792 <LI><A HREF="#10_67_5">Example</A></LI>
 793 <LI><A HREF="#10_67_6">See Also</A></LI>
 794 </UL>
 795 <LI><A HREF="#ippAddRange">ippAddRange()</A></LI>
 796 <UL>
 797 <LI><A HREF="#10_68_1">Usage</A></LI>
 798 <LI><A HREF="#10_68_2">Arguments</A></LI>
 799 <LI><A HREF="#10_68_3">Returns</A></LI>
 800 <LI><A HREF="#10_68_4">Description</A></LI>
 801 <LI><A HREF="#10_68_5">Example</A></LI>
 802 <LI><A HREF="#10_68_6">See Also</A></LI>
 803 </UL>
 804 <LI><A HREF="#ippAddRanges">ippAddRanges()</A></LI>
 805 <UL>
 806 <LI><A HREF="#10_69_1">Usage</A></LI>
 807 <LI><A HREF="#10_69_2">Arguments</A></LI>
 808 <LI><A HREF="#10_69_3">Returns</A></LI>
 809 <LI><A HREF="#10_69_4">Description</A></LI>
 810 <LI><A HREF="#10_69_5">Example</A></LI>
 811 <LI><A HREF="#10_69_6">See Also</A></LI>
 812 </UL>
 813 <LI><A HREF="#ippAddResolution">ippAddResolution()</A></LI>
 814 <UL>
 815 <LI><A HREF="#10_70_1">Usage</A></LI>
 816 <LI><A HREF="#10_70_2">Arguments</A></LI>
 817 <LI><A HREF="#10_70_3">Returns</A></LI>
 818 <LI><A HREF="#10_70_4">Description</A></LI>
 819 <LI><A HREF="#10_70_5">Example</A></LI>
 820 <LI><A HREF="#10_70_6">See Also</A></LI>
 821 </UL>
 822 <LI><A HREF="#ippAddResolutions">ippAddResolutions()</A></LI>
 823 <UL>
 824 <LI><A HREF="#10_71_1">Usage</A></LI>
 825 <LI><A HREF="#10_71_2">Arguments</A></LI>
 826 <LI><A HREF="#10_71_3">Returns</A></LI>
 827 <LI><A HREF="#10_71_4">Description</A></LI>
 828 <LI><A HREF="#10_71_5">Example</A></LI>
 829 <LI><A HREF="#10_71_6">See Also</A></LI>
 830 </UL>
 831 <LI><A HREF="#ippAddSeparator">ippAddSeparator()</A></LI>
 832 <UL>
 833 <LI><A HREF="#10_72_1">Usage</A></LI>
 834 <LI><A HREF="#10_72_2">Arguments</A></LI>
 835 <LI><A HREF="#10_72_3">Returns</A></LI>
 836 <LI><A HREF="#10_72_4">Description</A></LI>
 837 <LI><A HREF="#10_72_5">Example</A></LI>
 838 <LI><A HREF="#10_72_6">See Also</A></LI>
 839 </UL>
 840 <LI><A HREF="#ippAddString">ippAddString()</A></LI>
 841 <UL>
 842 <LI><A HREF="#10_73_1">Usage</A></LI>
 843 <LI><A HREF="#10_73_2">Arguments</A></LI>
 844 <LI><A HREF="#10_73_3">Returns</A></LI>
 845 <LI><A HREF="#10_73_4">Description</A></LI>
 846 <LI><A HREF="#10_73_5">Example</A></LI>
 847 <LI><A HREF="#10_73_6">See Also</A></LI>
 848 </UL>
 849 <LI><A HREF="#ippAddStrings">ippAddStrings()</A></LI>
 850 <UL>
 851 <LI><A HREF="#10_74_1">Usage</A></LI>
 852 <LI><A HREF="#10_74_2">Arguments</A></LI>
 853 <LI><A HREF="#10_74_3">Returns</A></LI>
 854 <LI><A HREF="#10_74_4">Description</A></LI>
 855 <LI><A HREF="#10_74_5">Example</A></LI>
 856 <LI><A HREF="#10_74_6">See Also</A></LI>
 857 </UL>
 858 <LI><A HREF="#ippDateToTime">ippDateToTime()</A></LI>
 859 <UL>
 860 <LI><A HREF="#10_75_1">Usage</A></LI>
 861 <LI><A HREF="#10_75_2">Arguments</A></LI>
 862 <LI><A HREF="#10_75_3">Returns</A></LI>
 863 <LI><A HREF="#10_75_4">Description</A></LI>
 864 <LI><A HREF="#10_75_5">Example</A></LI>
 865 <LI><A HREF="#10_75_6">See Also</A></LI>
 866 </UL>
 867 <LI><A HREF="#ippDelete">ippDelete()</A></LI>
 868 <UL>
 869 <LI><A HREF="#10_76_1">Usage</A></LI>
 870 <LI><A HREF="#10_76_2">Arguments</A></LI>
 871 <LI><A HREF="#10_76_3">Description</A></LI>
 872 <LI><A HREF="#10_76_4">Example</A></LI>
 873 <LI><A HREF="#10_76_5">See Also</A></LI>
 874 </UL>
 875 <LI><A HREF="#ippFindAttribute">ippFindAttribute()</A></LI>
 876 <UL>
 877 <LI><A HREF="#10_77_1">Usage</A></LI>
 878 <LI><A HREF="#10_77_2">Arguments</A></LI>
 879 <LI><A HREF="#10_77_3">Returns</A></LI>
 880 <LI><A HREF="#10_77_4">Description</A></LI>
 881 <LI><A HREF="#10_77_5">Example</A></LI>
 882 <LI><A HREF="#10_77_6">See Also</A></LI>
 883 </UL>
 884 <LI><A HREF="#ippLength">ippLength()</A></LI>
 885 <UL>
 886 <LI><A HREF="#10_78_1">Usage</A></LI>
 887 <LI><A HREF="#10_78_2">Arguments</A></LI>
 888 <LI><A HREF="#10_78_3">Returns</A></LI>
 889 <LI><A HREF="#10_78_4">Description</A></LI>
 890 <LI><A HREF="#10_78_5">Example</A></LI>
 891 <LI><A HREF="#10_78_6">See Also</A></LI>
 892 </UL>
 893 <LI><A HREF="#ippNew">ippNew()</A></LI>
 894 <UL>
 895 <LI><A HREF="#10_79_1">Usage</A></LI>
 896 <LI><A HREF="#10_79_2">Returns</A></LI>
 897 <LI><A HREF="#10_79_3">Description</A></LI>
 898 <LI><A HREF="#10_79_4">Example</A></LI>
 899 <LI><A HREF="#10_79_5">See Also</A></LI>
 900 </UL>
 901 <LI><A HREF="#ippPort">ippPort()</A></LI>
 902 <UL>
 903 <LI><A HREF="#10_80_1">Usage</A></LI>
 904 <LI><A HREF="#10_80_2">Returns</A></LI>
 905 <LI><A HREF="#10_80_3">Description</A></LI>
 906 <LI><A HREF="#10_80_4">Example</A></LI>
 907 <LI><A HREF="#10_80_5">See Also</A></LI>
 908 </UL>
 909 <LI><A HREF="#ippRead">ippRead()</A></LI>
 910 <UL>
 911 <LI><A HREF="#10_81_1">Usage</A></LI>
 912 <LI><A HREF="#10_81_2">Arguments</A></LI>
 913 <LI><A HREF="#10_81_3">Returns</A></LI>
 914 <LI><A HREF="#10_81_4">Description</A></LI>
 915 <LI><A HREF="#10_81_5">Example</A></LI>
 916 <LI><A HREF="#10_81_6">See Also</A></LI>
 917 </UL>
 918 <LI><A HREF="#ippSetPort">ippSetPort()</A></LI>
 919 <UL>
 920 <LI><A HREF="#10_82_1">Usage</A></LI>
 921 <LI><A HREF="#10_82_2">Arguments</A></LI>
 922 <LI><A HREF="#10_82_3">Description</A></LI>
 923 <LI><A HREF="#10_82_4">Example</A></LI>
 924 <LI><A HREF="#10_82_5">See Also</A></LI>
 925 </UL>
 926 <LI><A HREF="#ippTimeToDate">ippTimeToDate()</A></LI>
 927 <UL>
 928 <LI><A HREF="#10_83_1">Usage</A></LI>
 929 <LI><A HREF="#10_83_2">Arguments</A></LI>
 930 <LI><A HREF="#10_83_3">Returns</A></LI>
 931 <LI><A HREF="#10_83_4">Description</A></LI>
 932 <LI><A HREF="#10_83_5">Example</A></LI>
 933 <LI><A HREF="#10_83_6">See Also</A></LI>
 934 </UL>
 935 <LI><A HREF="#ippWrite">ippWrite()</A></LI>
 936 <UL>
 937 <LI><A HREF="#10_84_1">Usage</A></LI>
 938 <LI><A HREF="#10_84_2">Arguments</A></LI>
 939 <LI><A HREF="#10_84_3">Returns</A></LI>
 940 <LI><A HREF="#10_84_4">Description</A></LI>
 941 <LI><A HREF="#10_84_5">Example</A></LI>
 942 <LI><A HREF="#10_84_6">See Also</A></LI>
 943 </UL>
 944 <LI><A HREF="#ppdClose">ppdClose()</A></LI>
 945 <UL>
 946 <LI><A HREF="#10_85_1">Usage</A></LI>
 947 <LI><A HREF="#10_85_2">Arguments</A></LI>
 948 <LI><A HREF="#10_85_3">Description</A></LI>
 949 <LI><A HREF="#10_85_4">Example</A></LI>
 950 <LI><A HREF="#10_85_5">See Also</A></LI>
 951 </UL>
 952 <LI><A HREF="#ppdConflicts">ppdConflicts()</A></LI>
 953 <UL>
 954 <LI><A HREF="#10_86_1">Usage</A></LI>
 955 <LI><A HREF="#10_86_2">Arguments</A></LI>
 956 <LI><A HREF="#10_86_3">Returns</A></LI>
 957 <LI><A HREF="#10_86_4">Description</A></LI>
 958 <LI><A HREF="#10_86_5">Example</A></LI>
 959 <LI><A HREF="#10_86_6">See Also</A></LI>
 960 </UL>
 961 <LI><A HREF="#ppdEmit">ppdEmit()</A></LI>
 962 <UL>
 963 <LI><A HREF="#10_87_1">Usage</A></LI>
 964 <LI><A HREF="#10_87_2">Arguments</A></LI>
 965 <LI><A HREF="#10_87_3">Returns</A></LI>
 966 <LI><A HREF="#10_87_4">Description</A></LI>
 967 <LI><A HREF="#10_87_5">Example</A></LI>
 968 <LI><A HREF="#10_87_6">See Also</A></LI>
 969 </UL>
 970 <LI><A HREF="#ppdEmitFd">ppdEmitFd()</A></LI>
 971 <UL>
 972 <LI><A HREF="#10_88_1">Usage</A></LI>
 973 <LI><A HREF="#10_88_2">Arguments</A></LI>
 974 <LI><A HREF="#10_88_3">Returns</A></LI>
 975 <LI><A HREF="#10_88_4">Description</A></LI>
 976 <LI><A HREF="#10_88_5">Example</A></LI>
 977 <LI><A HREF="#10_88_6">See Also</A></LI>
 978 </UL>
 979 <LI><A HREF="#ppdFindChoice">ppdFindChoice()</A></LI>
 980 <UL>
 981 <LI><A HREF="#10_89_1">Usage</A></LI>
 982 <LI><A HREF="#10_89_2">Arguments</A></LI>
 983 <LI><A HREF="#10_89_3">Returns</A></LI>
 984 <LI><A HREF="#10_89_4">Description</A></LI>
 985 <LI><A HREF="#10_89_5">Example</A></LI>
 986 <LI><A HREF="#10_89_6">See Also</A></LI>
 987 </UL>
 988 <LI><A HREF="#ppdFindMarkedChoice">ppdFindMarkedChoice()</A></LI>
 989 <UL>
 990 <LI><A HREF="#10_90_1">Usage</A></LI>
 991 <LI><A HREF="#10_90_2">Arguments</A></LI>
 992 <LI><A HREF="#10_90_3">Returns</A></LI>
 993 <LI><A HREF="#10_90_4">Description</A></LI>
 994 <LI><A HREF="#10_90_5">Example</A></LI>
 995 <LI><A HREF="#10_90_6">See Also</A></LI>
 996 </UL>
 997 <LI><A HREF="#ppdFindOption">ppdFindOption()</A></LI>
 998 <UL>
 999 <LI><A HREF="#10_91_1">Usage</A></LI>
1000 <LI><A HREF="#10_91_2">Arguments</A></LI>
1001 <LI><A HREF="#10_91_3">Returns</A></LI>
1002 <LI><A HREF="#10_91_4">Description</A></LI>
1003 <LI><A HREF="#10_91_5">Example</A></LI>
1004 <LI><A HREF="#10_91_6">See Also</A></LI>
1005 </UL>
1006 <LI><A HREF="#ppdIsMarked">ppdIsMarked()</A></LI>
1007 <UL>
1008 <LI><A HREF="#10_92_1">Usage</A></LI>
1009 <LI><A HREF="#10_92_2">Arguments</A></LI>
1010 <LI><A HREF="#10_92_3">Returns</A></LI>
1011 <LI><A HREF="#10_92_4">Description</A></LI>
1012 <LI><A HREF="#10_92_5">Example</A></LI>
1013 <LI><A HREF="#10_92_6">See Also</A></LI>
1014 </UL>
1015 <LI><A HREF="#ppdMarkDefaults">ppdMarkDefaults()</A></LI>
1016 <UL>
1017 <LI><A HREF="#10_93_1">Usage</A></LI>
1018 <LI><A HREF="#10_93_2">Arguments</A></LI>
1019 <LI><A HREF="#10_93_3">Description</A></LI>
1020 <LI><A HREF="#10_93_4">Example</A></LI>
1021 <LI><A HREF="#10_93_5">See Also</A></LI>
1022 </UL>
1023 <LI><A HREF="#ppdMarkOption">ppdMarkOption()</A></LI>
1024 <UL>
1025 <LI><A HREF="#10_94_1">Usage</A></LI>
1026 <LI><A HREF="#10_94_2">Arguments</A></LI>
1027 <LI><A HREF="#10_94_3">Returns</A></LI>
1028 <LI><A HREF="#10_94_4">Description</A></LI>
1029 <LI><A HREF="#10_94_5">Example</A></LI>
1030 <LI><A HREF="#10_94_6">See Also</A></LI>
1031 </UL>
1032 <LI><A HREF="#ppdOpen">ppdOpen()</A></LI>
1033 <UL>
1034 <LI><A HREF="#10_95_1">Usage</A></LI>
1035 <LI><A HREF="#10_95_2">Arguments</A></LI>
1036 <LI><A HREF="#10_95_3">Returns</A></LI>
1037 <LI><A HREF="#10_95_4">Description</A></LI>
1038 <LI><A HREF="#10_95_5">Example</A></LI>
1039 <LI><A HREF="#10_95_6">See Also</A></LI>
1040 </UL>
1041 <LI><A HREF="#ppdOpenFd">ppdOpenFd()</A></LI>
1042 <UL>
1043 <LI><A HREF="#10_96_1">Usage</A></LI>
1044 <LI><A HREF="#10_96_2">Arguments</A></LI>
1045 <LI><A HREF="#10_96_3">Returns</A></LI>
1046 <LI><A HREF="#10_96_4">Description</A></LI>
1047 <LI><A HREF="#10_96_5">Example</A></LI>
1048 <LI><A HREF="#10_96_6">See Also</A></LI>
1049 </UL>
1050 <LI><A HREF="#ppdOpenFile">ppdOpenFile()</A></LI>
1051 <UL>
1052 <LI><A HREF="#10_97_1">Usage</A></LI>
1053 <LI><A HREF="#10_97_2">Arguments</A></LI>
1054 <LI><A HREF="#10_97_3">Returns</A></LI>
1055 <LI><A HREF="#10_97_4">Description</A></LI>
1056 <LI><A HREF="#10_97_5">Example</A></LI>
1057 <LI><A HREF="#10_97_6">See Also</A></LI>
1058 </UL>
1059 <LI><A HREF="#ppdPageLength">ppdPageLength()</A></LI>
1060 <UL>
1061 <LI><A HREF="#10_98_1">Usage</A></LI>
1062 <LI><A HREF="#10_98_2">Arguments</A></LI>
1063 <LI><A HREF="#10_98_3">Returns</A></LI>
1064 <LI><A HREF="#10_98_4">Description</A></LI>
1065 <LI><A HREF="#10_98_5">Example</A></LI>
1066 <LI><A HREF="#10_98_6">See Also</A></LI>
1067 </UL>
1068 <LI><A HREF="#ppdPageSize">ppdPageSize()</A></LI>
1069 <UL>
1070 <LI><A HREF="#10_99_1">Usage</A></LI>
1071 <LI><A HREF="#10_99_2">Arguments</A></LI>
1072 <LI><A HREF="#10_99_3">Returns</A></LI>
1073 <LI><A HREF="#10_99_4">Description</A></LI>
1074 <LI><A HREF="#10_99_5">Example</A></LI>
1075 <LI><A HREF="#10_99_6">See Also</A></LI>
1076 </UL>
1077 <LI><A HREF="#ppdPageWidth">ppdPageWidth()</A></LI>
1078 <UL>
1079 <LI><A HREF="#10_100_1">Usage</A></LI>
1080 <LI><A HREF="#10_100_2">Arguments</A></LI>
1081 <LI><A HREF="#10_100_3">Returns</A></LI>
1082 <LI><A HREF="#10_100_4">Description</A></LI>
1083 <LI><A HREF="#10_100_5">Example</A></LI>
1084 <LI><A HREF="#10_100_6">See Also</A></LI>
1085 </UL>
1086 </UL>
1087 <HR>
1088 <H1 ALIGN="RIGHT"><A NAME="1">Preface</A></H1>
1089 <P>This software programmers manual provides software programming
1090  information for the Common UNIX Printing System (&quot;CUPS&quot;) Version
1091  1.1.14.</P>
1092 <H2><A NAME="1_1">System Overview</A></H2>
1093 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
1094  systems. It has been developed by<A HREF="http://www.easysw.com"> Easy
1095  Software Products</A> to promote a standard printing solution for all
1096  UNIX vendors and users. CUPS provides the System V and Berkeley
1097  command-line interfaces.</P>
1098 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
1099  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
1100  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
1101  also supported with reduced functionality. CUPS adds network printer
1102  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
1103  options to support real-world printing under UNIX.</P>
1104 <P>CUPS also includes a customized version of GNU Ghostscript (currently
1105  based off GNU Ghostscript 5.50) and an image file RIP that are used to
1106  support non-PostScript printers. Sample drivers for HP and EPSON
1107  printers are included that use these filters.</P>
1108
1109 <!-- NEED 2in -->
1110 <H2><A NAME="1_2">Document Overview</A></H2>
1111 <P>This software programmers manual is organized into the following
1112  sections:</P>
1113 <UL>
1114 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI>
1115 <LI><A HREF="#CUPS_API">2 - The CUPS API</A></LI>
1116 <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></LI>
1117 <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></LI>
1118 <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></LI>
1119 <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI>
1120 <LI><A HREF="#CONSTANTS">B - Constants</A></LI>
1121 <LI><A HREF="#STRUCTURES">C - Structures</A></LI>
1122 <LI><A HREF="#FUNCTIONS">D - Functions</A></LI>
1123 </UL>
1124 <H2><A NAME="1_3">Notation Conventions</A></H2>
1125 <P>Various font and syntax conventions are used in this guide. Examples
1126  and their meanings and uses are explained below:
1127 <CENTER>
1128 <TABLE WIDTH="80%">
1129 <TR><TH>Example</TH><TD>&nbsp;&nbsp;&nbsp;</TD><TH>Description</TH></TR>
1130 <TR><TD>&nbsp;</TD></TR>
1131 <TR VALIGN="TOP"><TD><CODE>lpstat</CODE>
1132 <BR> <CODE>lpstat(1)</CODE></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>The names of commands;
1133  the first mention of a command or function in a chapter is followed by
1134  a manual page section number.</TD></TR>
1135 <TR><TD>&nbsp;</TD></TR>
1136 <TR VALIGN="TOP"><TD><VAR>/var</VAR>
1137 <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>
1138 File and directory names.</TD></TR>
1139 <TR><TD>&nbsp;</TD></TR>
1140 <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD>
1141 &nbsp;&nbsp;&nbsp;</TD><TD>Screen output.</TD></TR>
1142 <TR><TD>&nbsp;</TD></TR>
1143 <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD>
1144 &nbsp;&nbsp;&nbsp;</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
1145  in ALL CAPS.</TD></TR>
1146 <TR><TD>&nbsp;</TD></TR>
1147 <TR VALIGN="TOP"><TD>12.3</TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>Numbers in the text are
1148  written using the period (.) to indicate the decimal point.</TD></TR>
1149 </TABLE>
1150 </CENTER>
1151
1152 <!-- NEED 3in -->
1153 </P>
1154 <H2><A NAME="1_4">Abbreviations</A></H2>
1155  The following abbreviations are used throughout this manual:
1156 <UL>
1157 <DL>
1158 <DT>kb</DT>
1159 <DD>Kilobytes, or 1024 bytes
1160 <BR>&nbsp;</DD>
1161 <DT>Mb</DT>
1162 <DD>Megabytes, or 1048576 bytes
1163 <BR>&nbsp;</DD>
1164 <DT>Gb</DT>
1165 <DD>Gigabytes, or 1073741824 bytes
1166 <BR>&nbsp;</DD>
1167 </DL>
1168 </UL>
1169 <H2><A NAME="1_5">Other References</A></H2>
1170 <UL>
1171 <DL>
1172 <DT>CUPS Software Administrators Manual</DT>
1173 <DD>An administration guide for the CUPS software.
1174 <BR>&nbsp;</DD>
1175 <DT>CUPS Software Users Manual</DT>
1176 <DD>An end-user guide for using the CUPS software.
1177 <BR>&nbsp;</DD>
1178 </DL>
1179 </UL>
1180 <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1>
1181 <P>This chapter provides an overview of how the Common UNIX Printing
1182  System works.</P>
1183 <H2><A NAME="2_1">The Printing Problem</A></H2>
1184 <P>For years<I> the printing problem</I> has plagued UNIX. Unlike
1185  Microsoft&reg; Windows&reg; or Mac OS, UNIX has no standard interface or system
1186  in place for supporting printers. Among the solutions currently
1187  available, the Berkeley and System V printing systems are the most
1188  prevalent.</P>
1189 <P>These printing systems support line printers (text only) or
1190  PostScript printers (text and graphics), and with some coaxing they can
1191  be made to support a full range of printers and file formats. However,
1192  because each varient of the UNIX operating system uses a different
1193  printing system than the next developing printer drivers for a wide
1194  range of printers and operating systems is extremely difficult. That
1195  combined with the limited volume of customers for each UNIX varient has
1196  forced most printer vendors to give up supporting UNIX entirely.</P>
1197 <P>CUPS is designed to eliminate<I> the printing problem</I>. One common
1198  printing system can be used by all UNIX varients to support the
1199  printing needs of users. Printer vendors can use its modular filter
1200  interface to develop a single driver program that supports a wide range
1201  of file formats with little or no effort. Since CUPS provides both the
1202  System V and Berkeley printing commands, users (and applications) can
1203  reap the benefits of this new technology with no changes.</P>
1204 <H2><A NAME="2_2">The Technology</A></H2>
1205 <P>CUPS is based upon an emerging Internet standard called the Internet
1206  Printing Protocol. IPP has been embraced by dozens of printer and
1207  printer server manufacturers and is supported by Microsoft Windows
1208  2000.</P>
1209 <P>IPP defines a standard protocol for printing as well as managing
1210  print jobs and printer options like media size, resolution, and so
1211  forth. Like all IP-based protocols, IPP can be used locally or over the
1212  Internet to printers hundreds or thousands of miles away. Unlike other
1213  protocols, however, IPP also supports access control, authentication,
1214  and encryption, making it a much more capable and secure printing
1215  solution than older ones.</P>
1216 <P>IPP is layered on top of the Hyper-Text Transport Protocol (&quot;HTTP&quot;)
1217  which is the basis of web servers on the Internet. This allows users to
1218  view documentation, check status information on a printer or server,
1219  and manage their printers, classes, and jobs using their web browser.</P>
1220 <P>CUPS provides a complete IPP/1.1 based printing system that provides
1221  Basic, Digest, and local certificate authentication and user, domain,
1222  or IP-based access control. TLS encryption will be available in future
1223  versions of CUPS.</P>
1224 <H2><A NAME="2_3">Jobs</A></H2>
1225 <P>Each file or set of files that is submitted for printing is called a<I>
1226  job</I>. Jobs are identified by a unique number starting at 1 and are
1227  assigned to a particular destination, usually a printer. Jobs can also
1228  have options associated with them such as media size, number of copies,
1229  and priority.</P>
1230 <H2><A NAME="2_4">Classes</A></H2>
1231 <P>CUPS supports collections of printers known as<I> classes</I>. Jobs
1232  sent to a class are forwarded to the first available printer in the
1233  class.</P>
1234 <H2><A NAME="2_5">Filters</A></H2>
1235 <P>Filters allow a user or application to print many types of files
1236  without extra effort. Print jobs sent to a CUPS server are filtered
1237  before sending them to a printer. Some filters convert job files to
1238  different formats that the printer can understand. Others perform page
1239  selection and ordering tasks.</P>
1240 <P>CUPS provides filters for printing many types of image files, HP-GL/2
1241  files, PDF files, and text files. CUPS also supplies PostScript and
1242  image file Raster Image Processor (&quot;RIP&quot;) filters that convert
1243  PostScript or image files into bitmaps that can be sent to a raster
1244  printer.</P>
1245 <H2><A NAME="2_6">Backends</A></H2>
1246 <P>Backends perform the most important task of all - they send the
1247  filtered print data to the printer.</P>
1248 <P>CUPS provides backends for printing over parallel, serial, and USB
1249  ports, and over the network via the IPP, JetDirect (AppSocket), and
1250  Line Printer Daemon (&quot;LPD&quot;) protocols. Additional backends are
1251  available in network service packages such as the SMB backend included
1252  with the popular SAMBA software.</P>
1253 <P>Backends are also used to determine the available devices. On startup
1254  each backend is asked for a list of devices it supports, and any
1255  information that is available. This allows the parallel backend to tell
1256  CUPS that an EPSON Stylus Color 600 printer is attached to parallel
1257  port 1, for example.</P>
1258 <H2><A NAME="2_7">Printer Drivers</A></H2>
1259 <P>Printer drivers in CUPS consist of one of more filters specific to a
1260  printer. CUPS includes sample printer drivers for Hewlett-Packard
1261  LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
1262  and Stylus Photo printers. While these drivers do not generate optimal
1263  output for the different printer models, they do provide basic printing
1264  and demonstrate how you can write your own printer drivers and
1265  incorporate them into CUPS.</P>
1266 <H2><A NAME="2_8">Networking</A></H2>
1267 <P>Printers and classes on the local system are automatically shared
1268  with other systems on the network. This allows you to setup one system
1269  to print to a printer and use this system as a printer server or spool
1270  host for all of the others. Users may then select a local printer by
1271  name or a remote printer using &quot;name@server&quot;.</P>
1272 <P>CUPS also provides<I> implicit classes</I>, which are collections of
1273  printers and/or classes with the same name. This allows you to setup
1274  multiple servers pointing to the same physical network printer, for
1275  example, so that you aren't relying on a single system for printing.
1276  Because this also works with printer classes, you can setup multiple
1277  servers and printers and never worry about a single point of failure
1278  unless all of the printers and servers go down!</P>
1279 <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
1280 <P>This chapter describes the CUPS Application Programmers Interface
1281  (&quot;API&quot;).</P>
1282 <H2><A NAME="3_1">The CUPS API Library</A></H2>
1283 <P>The CUPS library provides a whole collection of interfaces needed to
1284  support the internal needs of the CUPS software as well as the needs of
1285  applications, filters, printer drivers, and backends.</P>
1286 <P>Unlike the rest of CUPS, the CUPS API library is provided under the
1287  GNU Library General Public License. This means that you can use the
1288  CUPS API library in both proprietary and open-source programs.</P>
1289 <P>Programs that use the CUPS API library typically will include the <CODE>
1290 &lt;cups/cups.h&gt;</CODE> header file:</P>
1291 <UL>
1292 <PRE>
1293 #include &lt;cups/cups.h&gt;
1294
1295 ...
1296
1297 jobid = cupsPrintFile(&quot;myprinter&quot;, &quot;filename.ps&quot;, &quot;title&quot;,
1298                       num_options, options);
1299 </PRE>
1300 </UL>
1301 <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS
1302  API library:</P>
1303 <UL>
1304 <PRE>
1305 <B>cc -o program program.c -lcups ENTER</B>
1306 </PRE>
1307 </UL>
1308 <P>Additional options and libraries may be required depending on the
1309  operating system and the location of the CUPS API library.</P>
1310 <H3><A NAME="3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></H3>
1311 <P>GNU autoconf is a popular configuration tool used by many programs.
1312  Add the following lines to your<VAR> configure.in file to check for the
1313  CUPS API library in your configuration script:</VAR></P>
1314 <UL>
1315 <PRE>
1316 AC_CHECK_LIB(socket,socket,
1317 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1318         LIBS=&quot;-lsocket $LIBS&quot;
1319 else
1320         echo &quot;Not using -lsocket since you are running IRIX.&quot;
1321 fi)
1322 AC_CHECK_LIB(nsl,gethostbyaddr,
1323 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1324         LIBS=&quot;-lnsl $LIBS&quot;
1325 else
1326         echo &quot;Not using -lnsl since you are running IRIX.&quot;
1327 fi)
1328
1329 AC_CHECK_LIB(cups,httpConnect)
1330 </PRE>
1331 </UL>
1332 <H2><A NAME="3_2">Printing Services</A></H2>
1333 <P>The CUPS API library provides some basic printing services for
1334  applications that need to print files.</P>
1335 <H3><A NAME="3_2_1">Include Files</A></H3>
1336 <P>The include file used by all of these functions is <CODE>
1337 &lt;cups/cups.h&gt;</CODE>:</P>
1338 <UL>
1339 <PRE>
1340 #include &lt;cups/cups.h&gt;
1341 </PRE>
1342 </UL>
1343 <H3><A NAME="3_2_2">Printing a File</A></H3>
1344 <P>The CUPS API provides two functions for printing files. The first is <CODE>
1345 cupsPrintFile</CODE> which prints a single named file:</P>
1346 <UL>
1347 <PRE>
1348 #include &lt;cups/cups.h&gt;
1349
1350 ...
1351
1352 int jobid;
1353
1354 ...
1355
1356 jobid = cupsPrintFile(&quot;<I>name</I>&quot;, &quot;<I>filename</I>&quot;, &quot;<I>title</I>&quot;, 0, NULL);
1357 </PRE>
1358 </UL>
1359 <P>The <CODE>name</CODE> string is the name of the printer or class to
1360  print to. The <CODE>filename</CODE> string is the name of the file to
1361  print. The <CODE>title</CODE> string is the name of the print job, e.g.
1362  &quot;Acme Word Document&quot;.</P>
1363 <P>The return value is a unique ID number for the print job or 0 if
1364  there was an error.</P>
1365 <H3><A NAME="3_2_3">Printing Multiple Files</A></H3>
1366 <P>The second printing function is <CODE>cupsPrintFiles</CODE>:</P>
1367 <UL>
1368 <PRE>
1369 #include &lt;cups/cups.h&gt;
1370
1371 ...
1372
1373 int        jobid;
1374 int        num_files;
1375 const char *files[100];
1376 ...
1377
1378 jobid = cupsPrintFiles(&quot;name&quot;, <I>num_files</I>, <I>files</I>, &quot;title&quot;, 0, NULL);
1379 </PRE>
1380 </UL>
1381 <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
1382 , you pass a file count (<CODE>num_files</CODE>) and filename pointer
1383  array (<CODE>files</CODE>) for each file that you want to print.</P>
1384 <P>As with <CODE>cupsPrintFile()</CODE>, the return value is a unique ID
1385  for the print job.</P>
1386 <H3><A NAME="3_2_4">Cancelling Jobs</A></H3>
1387 <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:</P>
1388 <UL>
1389 <PRE>
1390 #include &lt;cups/cups.h&gt;
1391
1392 ...
1393
1394 int jobid;
1395 int status;
1396 ...
1397
1398 status = cupsCancelJob(&quot;<I>name</I>&quot;, <I>jobid</I>);
1399 </PRE>
1400 </UL>
1401 <P>The <CODE>name</CODE> string specifies the destination and is used to
1402  determine the server to send the request to. The <CODE>jobid</CODE>
1403  value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
1404  or <CODE>cupsPrintFiles()</CODE> call.</P>
1405 <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
1406  successfully cancelled and <CODE>0</CODE> if there was an error.</P>
1407 <H3><A NAME="3_2_5">Getting the Available Printers and Classes</A></H3>
1408 <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list of
1409  the available printers, classes, and instances that a user has defined:</P>
1410 <UL>
1411 <PRE>
1412 #include &lt;cups/cups.h&gt;
1413
1414 ...
1415
1416 int         num_dests;
1417 cups_dest_t *dests;
1418
1419 ...
1420
1421 num_dests = cupsGetDests(&amp;dests);
1422 </PRE>
1423 </UL>
1424 <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure
1425  which defines the printer or class name, the instance name (if any), if
1426  it is the default destination, and the default options the user has
1427  defined for the destination:</P>
1428 <UL>
1429 <PRE>
1430 typedef struct               /**** Destination ****/
1431 {
1432   char          *name,       /* Printer or class name */
1433                 *instance;   /* Local instance name or NULL */
1434   int           is_default;  /* Is this printer the default? */
1435   int           num_options; /* Number of options */
1436   cups_option_t *options;    /* Options */
1437 } cups_dest_t;
1438 </PRE>
1439 </UL>
1440 <P>The destinations are sorted by name and instance for your
1441  convenience. Once you have the list of available destinations, you can
1442  lookup a specific destination using the <CODE>cupsGetDest()</CODE>
1443  function:</P>
1444 <UL>
1445 <PRE>
1446 #include &lt;cups/cups.h&gt;
1447
1448 ...
1449
1450 int         num_dests;
1451 cups_dest_t *dests;
1452 cups_dest_t *mydest;
1453
1454 ...
1455
1456 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1457 </PRE>
1458 </UL>
1459 <P>The <CODE>name</CODE> string is the printer or class name. You can
1460  pass a value of <CODE>NULL</CODE> to get the default destination.</P>
1461 <P>The <CODE>instance</CODE> string is the user-defined instance name.
1462  Pass <CODE>NULL</CODE> to select the default instance, e.g. &quot;name&quot;
1463  instead of &quot;name/instance&quot;.</P>
1464 <H3><A NAME="3_2_6">Printing with Options</A></H3>
1465 <P>All of the previous printing examples have passed <CODE>0</CODE> and <CODE>
1466 NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
1467  and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments
1468  are the number of options and a pointer to the option array:</P>
1469 <UL>
1470 <PRE>
1471 int cupsPrintFile(const char *name, const char *filename, const char *title,
1472                   int num_options, cups_option_t *options);
1473 int cupsPrintFiles(const char *name, int num_files, const char **files,
1474                    const char *title, int num_options,
1475                    cups_option_t *options);
1476 </PRE>
1477 </UL>
1478 <P>The <CODE>cups_option_t</CODE> structure holds each option and its
1479  value. These are converted as needed and passed to the CUPS server when
1480  printing a file.</P>
1481 <P>The simplest way of handling options is to use the <CODE>num_options</CODE>
1482  and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
1483  structure described earlier:</P>
1484 <UL>
1485 <PRE>
1486 #include &lt;cups/cups.h&gt;
1487
1488 ...
1489
1490 int         jobid;
1491 int         num_dests;
1492 cups_dest_t *dests;
1493 cups_dest_t *mydest;
1494
1495 ...
1496
1497 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1498
1499 jobid  = cupsPrintFile(mydest-&gt;name, &quot;filename&quot;, &quot;title&quot;,
1500                        mydest-&gt;num_options, mydest-&gt;options);
1501 </PRE>
1502 </UL>
1503 <P>This effectively uses the options a user has previous selected
1504  without a lot of code.</P>
1505 <H3><A NAME="3_2_7">Setting Printer Options</A></H3>
1506 <P>Options can also be set by your program using the <CODE>
1507 cupsAddOption()</CODE> function:</P>
1508 <UL>
1509 <PRE>
1510 #include &lt;cups/cups.h&gt;
1511
1512 ...
1513
1514 int           num_options;
1515 cups_option_t *options;
1516
1517 ...
1518
1519 num_options = 0;
1520 options     = NULL;
1521
1522 ...
1523
1524 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1525 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1526 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1527 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1528 </PRE>
1529 </UL>
1530 <P>The <CODE>name</CODE> string is the name of the option, and the <CODE>
1531 value</CODE> string is the value for that option.</P>
1532 <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
1533  options. Since adding two options with the same name overwrites the
1534  first value with the second, do not assume that calling <CODE>
1535 cupsAddOptions()</CODE> 20 times will result in 20 options.</P>
1536 <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the
1537  options:</P>
1538 <UL>
1539 <PRE>
1540 #include &lt;cups/cups.h&gt;
1541
1542 ...
1543
1544 int           num_options;
1545 cups_option_t *options;
1546
1547 ...
1548
1549 cupsFreeOptions(num_options, options);
1550 </PRE>
1551 </UL>
1552 <H3><A NAME="3_2_8">Getting Errors</A></H3>
1553 <P>If any of the CUPS API printing functions returns an error, the
1554  reason for that error can be found by calling <CODE>cupsLastError()</CODE>
1555  and <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE>
1556  returns the last IPP error code that was encountered. <CODE>
1557 cupsErrorString()</CODE> converts the error code to a localized message
1558  string suitable for presentation to the user:</P>
1559 <UL>
1560 <PRE>
1561 #include &lt;cups/cups.h&gt;
1562
1563 ...
1564
1565 int jobid;
1566
1567 ...
1568
1569 if (jobid == 0)
1570   puts(cupsErrorString(cupsLastError()));
1571 </PRE>
1572 </UL>
1573 <H3><A NAME="3_2_9">Passwords and Authentication</A></H3>
1574 <P>CUPS supports authentication of any request, including submission of
1575  print jobs. The default mechanism for getting the username and password
1576  is to use the login user and a password from the console.</P>
1577 <P>To support other types of applications, in particular Graphical User
1578  Interfaces (&quot;GUIs&quot;), the CUPS API provides functions to set the default
1579  username and to register a callback function that returns a password
1580  string.</P>
1581 <P>The<A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>
1582  function is used to set a password callback in your program. Only one
1583  function can be used at any time.</P>
1584 <P>The<A HREF="#cupsSetUser"> <CODE>cupsSetUser()</CODE></A> function
1585  sets the current username for authentication. This function can be
1586  called by your password callback function to change the current
1587  username as needed.</P>
1588 <P>The following example shows a simple password callback that gets a
1589  username and password from the user:</P>
1590 <UL>
1591 <PRE>
1592 #include &lt;cups/cups.h&gt;
1593
1594 const char *
1595 my_password_cb(const char *prompt)
1596 {
1597   char  user[65];
1598
1599
1600   puts(prompt);
1601
1602  /* Get a username from the user */
1603   printf(&quot;Username: &quot;);
1604   if (fgets(user, sizeof(user), stdin) == NULL)
1605     return (NULL);
1606
1607  /* Strip the newline from the string and set the user */
1608   user[strlen(user) - 1] = '\0';
1609
1610   cupsSetUser(user);
1611
1612  /* Use getpass() to ask for the password... */
1613   return (getpass(&quot;Password: &quot;));
1614 }
1615
1616 ...
1617
1618 cupsSetPasswordCB(my_password_cb);
1619 </PRE>
1620 </UL>
1621 <P>Similarly, a GUI interface could display the prompt string in a
1622  window with input fields for the username and password. The username
1623  should probably default to the value of<A HREF="#cupsUser"> <CODE>
1624 cupsUser()</CODE></A> to make things easier on the user.</P>
1625 <H2><A NAME="3_3">PPD Services</A></H2>
1626 <P>CUPS includes functions to access and manipulate PostScript Printer
1627  Description (&quot;PPD&quot;) files that are used with the printer drivers in
1628  CUPS.</P>
1629 <P>Each PPD file enumerates the available features provided by a
1630  printer, including conflict information for specific options (e.g.
1631  can't duplex output on envelopes.)</P>
1632 <H3><A NAME="3_3_1">Include Files</A></H3>
1633 <P>Include the <CODE>&lt;cups/ppd.h&gt;</CODE> header file to use the PPD
1634  functions:</P>
1635 <UL>
1636 <PRE>
1637 #include &lt;cups/ppd.h&gt;
1638 </PRE>
1639 </UL>
1640 <P>This header file is also included by the <CODE>&lt;cups/cups.h&gt;</CODE>
1641  header file.</P>
1642 <H3><A NAME="3_3_2">Getting a PPD File for a Printer</A></H3>
1643 <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
1644  named printer or class:</P>
1645 <UL>
1646 <PRE>
1647 #include &lt;cups/cups.h&gt;
1648
1649 ...
1650
1651 const char *filename;
1652
1653 filename = cupsGetPPD(&quot;<I>name</I>&quot;);
1654 </PRE>
1655 </UL>
1656 <P>The <CODE>name</CODE> string is the name of the printer or class,
1657  including the remote server name as appropriate (e.g.
1658  &quot;printer@server&quot;.)</P>
1659 <P>The return value is a pointer to a filename in static storage; this
1660  value is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If
1661  the printer or class does not exist, a <CODE>NULL</CODE> pointer will
1662  be returned.</P>
1663 <H3><A NAME="3_3_3">Loading a PPD File</A></H3>
1664 <P>The <CODE>ppdOpenFile()</CODE> function &quot;opens&quot; a PPD file and loads
1665  it into memory:</P>
1666 <UL>
1667 <PRE>
1668 #include &lt;cups/ppd.h&gt;
1669
1670 ...
1671
1672 ppd_file_t *ppd;
1673
1674 ppd = ppdOpenFile(&quot;<I>filename</I>&quot;);
1675 </PRE>
1676 </UL>
1677 <P>The <CODE>filename</CODE> string is the name of the file to load,
1678  such as the value returned by the <CODE>cupsGetPPD()</CODE> function.</P>
1679 <P>The return value is a pointer to a structure describing the contents
1680  of the PPD file or NULL if the PPD file could not be read.</P>
1681 <H3><A NAME="3_3_4">Freeing PPD File Information</A></H3>
1682 <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE>
1683  function to free all memory that has been used:</P>
1684 <UL>
1685 <PRE>
1686 #include &lt;cups/ppd.h&gt;
1687
1688 ...
1689
1690 ppd_file_t *ppd;
1691
1692 ...
1693
1694 ppdClose(ppd);
1695 </PRE>
1696 </UL>
1697 <H3><A NAME="3_3_5">The PPD File Structure</A></H3>
1698 <P>Each PPD file contains a number of capability attributes, printer
1699  options, and conflict definitions. The page size options also include
1700  the physical margins for the printer and the minimum and maximum sizes
1701  for the printer. All of this information is stored in the <CODE>
1702 ppd_file_t</CODE> structure.</P>
1703 <H4>Capabilities</H4>
1704 <P>Each PPD file contains a number of informational attributes that
1705  describe the capabilities of the printer. These are provided in the <CODE>
1706 ppd_file_t</CODE> structure in the following members:
1707 <CENTER>
1708 <TABLE BORDER="1" WIDTH="80%">
1709 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
1710 <TR><TD><CODE>accurate_screens</CODE></TD><TD><CODE>int</CODE></TD><TD>1
1711  = supports accurate screens</TD></TR>
1712 <TR><TD><CODE>color_device</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1713  color device</TD></TR>
1714 <TR><TD><CODE>colorspace</CODE></TD><TD><CODE>ppd_cs_t</CODE></TD><TD>
1715 Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB,
1716  PPD_CS_RGBK, PPD_CS_N</TD></TR>
1717 <TR><TD><CODE>contone_only</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1718  printer is continuous tone only</TD></TR>
1719 <TR><TD><CODE>num_emulations
1720 <BR> emulations</CODE></TD><TD><CODE>int
1721 <BR> ppd_emul_t *</CODE></TD><TD>Emulations supported by the printer</TD>
1722 </TR>
1723 <TR><TD><CODE>flip_duplex</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1724  need to flip odd pages when duplexing</TD></TR>
1725 <TR><TD><CODE>num_fonts
1726 <BR> fonts</CODE></TD><TD><CODE>int
1727 <BR> char **</CODE></TD><TD>The fonts available on the printer.</TD></TR>
1728 <TR><TD><CODE>jcl_begin
1729 <BR> jcl_ps
1730 <BR> jcl_end</CODE></TD><TD><CODE>char *</CODE></TD><TD>Job Control
1731  Language commands for PostScript output</TD></TR>
1732 <TR><TD><CODE>landscape</CODE></TD><TD><CODE>int</CODE></TD><TD>
1733 Landscape orientation, -90 or 90 degrees</TD></TR>
1734 <TR><TD><CODE>lang_encoding</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1735 The character used for the option strings</TD></TR>
1736 <TR><TD><CODE>lang_version</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1737 The language used for the options strings (English, French, etc.)</TD></TR>
1738 <TR><TD><CODE>language_level</CODE></TD><TD><CODE>int</CODE></TD><TD>
1739 PostScript language level, 1 to 3</TD></TR>
1740 <TR><TD><CODE>manual_copies</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1741  Copies are done manually</TD></TR>
1742 <TR><TD><CODE>model_number</CODE></TD><TD><CODE>int</CODE></TD><TD>
1743 Driver-specific model number.</TD></TR>
1744 <TR><TD><CODE>patches</CODE></TD><TD><CODE>char *</CODE></TD><TD>Patch
1745  commands to send to the printer</TD></TR>
1746 <TR><TD><CODE>manufacturer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1747 The Manufacturer attribute from the PPD file, if any</TD></TR>
1748 <TR><TD><CODE>modelname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1749  ModelName attribute from the PPD file</TD></TR>
1750 <TR><TD><CODE>nickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1751  NickName attribute from the PPD file, if any</TD></TR>
1752 <TR><TD><CODE>product</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1753  Product attribute from the PPD file, if any</TD></TR>
1754 <TR><TD><CODE>shortnickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1755 The ShortNickName attribute from the PPD file, if any</TD></TR>
1756 <TR><TD><CODE>throughput</CODE></TD><TD><CODE>int</CODE></TD><TD>Number
1757  of pages per minute</TD></TR>
1758 <TR><TD><CODE>ttrasterizer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1759 The TruType font rasterizer (Type42)</TD></TR>
1760 <TR><TD><CODE>variable_sizes</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1761  supports variable sizes</TD></TR>
1762 </TABLE>
1763 </CENTER>
1764 </P>
1765 <H4>Options and Groups</H4>
1766 <P>PPD files support multiple options, which are stored in <CODE>
1767 ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by the PPD
1768  functions.</P>
1769 <P>Each option in turn is associated with a group stored in the <CODE>
1770 ppd_group_t</CODE> structure. Groups can be specified in the PPD file;
1771  if an option is not associated with a group then it is put in a
1772  &quot;General&quot; or &quot;Extra&quot; group depending on the option.</P>
1773 <P>Groups can also have sub-groups; CUPS currently limits the depth of
1774  sub-groups to 1 level to reduce programming complexity.</P>
1775 <H4>Conflicts</H4>
1776 <P>PPD files support specification of conflict conditions between
1777  different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
1778  structures which specify the options that conflict with each other.</P>
1779 <H4>Page Sizes</H4>
1780 <P>PPD files specify all of the available pages sizes and the physical
1781  margins associated with them. These sizes are stored in <CODE>
1782 ppd_size_t</CODE> structures and are available in the <CODE>num_sizes</CODE>
1783  and <CODE>sizes</CODE> members of the <CODE>ppd_file_t</CODE>
1784  structure. You can lookup a particular page size with the <CODE>
1785 ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and <CODE>
1786 ppdPageSize()</CODE> functions:</P>
1787 <UL>
1788 <PRE>
1789 #include &lt;cups/ppd.h&gt;
1790
1791 ...
1792
1793 ppd_file_t *ppd;
1794 ppd_size_t *size;
1795 float      width;
1796 float      length;
1797
1798 ...
1799
1800 size   = ppdPageSize(ppd, &quot;<I>size</I>&quot;);
1801 width  = ppdPageWidth(ppd, &quot;<I>size</I>&quot;);
1802 length = ppdPageLength(ppd, &quot;<I>size</I>&quot;);
1803 </PRE>
1804 </UL>
1805 <P>The <CODE>size</CODE> string is the named page size option. The width
1806  and length are in points; there are 72 points per inch. The <CODE>
1807 ppd_size_t</CODE> structure contains the width, length, and margin
1808  information:</P>
1809 <UL>
1810 <PRE>
1811 typedef struct    /**** Page Sizes ****/
1812 {
1813   int   marked;   /* Page size selected? */
1814   char  name[41]; /* Media size option */
1815   float width,    /* Width of media in points */
1816         length,   /* Length of media in points */
1817         left,     /* Left printable margin in points */
1818         bottom,   /* Bottom printable margin in points */
1819         right,    /* Right printable margin in points */
1820         top;      /* Top printable margin in points */
1821 } ppd_size_t;
1822 </PRE>
1823 </UL>
1824 <H4>Custom Page Sizes</H4>
1825 <P>Besides the standard page sizes listed in a PPD file, some printers
1826  support variable or custom page sizes. If <CODE>variables_sizes</CODE>
1827  is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and <CODE>
1828 custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> structure
1829  define the limits of the variable sizes.</P>
1830 <P>To get the resulting media size, use a page size string of <CODE>
1831 Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE> and <CODE>
1832 length</CODE> are integer values in points:</P>
1833 <UL>
1834 <PRE>
1835 Custom.612x792   [8.5 inches wide, 11 inches long]
1836 Custom.1224x792  [17 inches wide, 11 inches long]
1837 </PRE>
1838 </UL>
1839 <H3><A NAME="3_3_6">Marking Options</A></H3>
1840 <P>Before marking any user-defined options, call the <CODE>
1841 ppdMarkDefaults()</CODE> function to mark the default options from the
1842  PPD file:</P>
1843 <UL>
1844 <PRE>
1845 #include &lt;cups/ppd.h&gt;
1846
1847 ...
1848
1849 ppd_file_t *ppd;
1850
1851 ...
1852
1853 ppdMarkDefaults(ppd);
1854 </PRE>
1855 </UL>
1856 <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark
1857  individual options:</P>
1858 <UL>
1859 <PRE>
1860 #include &lt;cups/ppd.h&gt;
1861
1862 ...
1863
1864 ppd_file_t *ppd;
1865 int        conflicts;
1866
1867 ...
1868
1869 conflicts = ppdMarkOption(ppd, &quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;);
1870 </PRE>
1871 </UL>
1872 <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
1873  particular option and choice, respectively. The return value is 0 if
1874  there are not conflicts created by the selection.</P>
1875 <P>CUPS also provides a convenience function for marking all options in
1876  the <CODE>cups_option_t</CODE> structure:</P>
1877 <UL>
1878 <PRE>
1879 #include &lt;cups/cups.h&gt;
1880
1881 ...
1882
1883 ppd_file_t    *ppd;
1884 int           num_options;
1885 cups_option_t *options;
1886 int           conflicts;
1887
1888 ...
1889
1890 conflicts = cupsMarkOptions(ppd, num_options, options);
1891 </PRE>
1892 </UL>
1893 <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
1894  IPP job template attributes to PPD options. The return value is the
1895  number of conflicts present.</P>
1896 <H3><A NAME="3_3_7">Checking for Conflicts</A></H3>
1897 <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
1898  functions return the number of conflicts with the currently marked
1899  options.</P>
1900 <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
1901  conflicts after you have marked all of the options:</P>
1902 <UL>
1903 <PRE>
1904 #include &lt;cups/cups.h&gt;
1905
1906 ...
1907
1908 ppd_file_t *ppd;
1909 int        conflicts;
1910
1911 ...
1912
1913 conflicts = ppdConflicts(ppd);
1914 </PRE>
1915 </UL>
1916 <P>The return value is the number of conflicting options, or 0 if there
1917  are no conflicts.</P>
1918 <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
1919 <P>This chapter describes how to write a file filter for CUPS.</P>
1920 <H2><A NAME="4_1">Overview</A></H2>
1921 <P>File filters are programs that convert from one or more MIME types to
1922  another type. Filters use a common command-line and environment
1923  interface that allows them to be joined as needed to print files to any
1924  type of printer.</P>
1925 <H3><A NAME="4_1_1">Security Considerations</A></H3>
1926 <P>Filters are normally run as a non-priviledged user, so the major
1927  security consideration is resource utilization - filters should not
1928  depend on unlimited amounts of memory and disk space.</P>
1929 <H3><A NAME="4_1_2">Users and Groups</A></H3>
1930 <P>The default CUPS configuration runs filters as user &quot;lp&quot; and group
1931  &quot;other&quot;.</P>
1932 <H3><A NAME="4_1_3">Temporary Files</A></H3>
1933 <P>Temporary files should be created in the directory specified by the
1934  &quot;TMPDIR&quot; environment variable. The<A HREF="#cupsTempFile"> <CODE>
1935 cupsTempFile()</CODE></A> function can be used to safely choose
1936  temporary files in this directory.</P>
1937 <H3><A NAME="4_1_4">Sending Messages to the User</A></H3>
1938 <P>The CUPS scheduler collects messages sent to the standard error file
1939  by the filter. These messages are relayed to the user based upon the
1940  scheduler <CODE>LogLevel</CODE> directive.</P>
1941 <P>The type of message is determined by an initial prefix sent on each
1942  line:</P>
1943 <UL>
1944 <LI><CODE>DEBUG:</CODE> - a debug message</LI>
1945 <LI><CODE>INFO:</CODE> - an informational message</LI>
1946 <LI><CODE>WARNING:</CODE> - a warning message</LI>
1947 <LI><CODE>ERROR:</CODE> - an error message</LI>
1948 <LI><CODE>PAGE:</CODE> - a page accounting message</LI>
1949 </UL>
1950 <P>If the line of text does not begin with any of the above prefixes, it
1951  is treated as a debug message. Text following the prefix is copied to
1952  the <CODE>printer-state-message</CODE> attribute for the printer, and
1953  also added to the<VAR> error_log</VAR> unless it is an informational or
1954  page accounting message.</P>
1955 <H3><A NAME="4_1_5">Page Accounting</A></H3>
1956 <P>Page accounting messages are used to inform the server when one or
1957  more pages are printed. Each line has the form:</P>
1958 <UL>
1959 <PRE>
1960 PAGE: page-number copy-count
1961 </PRE>
1962 </UL>
1963 <P>The<I> page-number</I> field is the current page number, starting at
1964  1. The<I> copy-count</I> field specifies the number of copies of that
1965  page that was produced.</P>
1966 <P>Page account messages are added to the<VAR> page_log</VAR> file and
1967  cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
1968  the job.</P>
1969 <H3><A NAME="4_1_6">Command-Line Arguments</A></H3>
1970 <P>Every filter accepts exactly 6 or 7 command-line arguments:</P>
1971 <UL>
1972 <PRE>
1973 printer job user title copies options [filename]
1974 </PRE>
1975 <LI><CODE>printer</CODE> - The name of the printer queue (normally this
1976  is the name of the program being run)</LI>
1977 <LI><CODE>job</CODE> - The numeric job ID for the job being printed</LI>
1978 <LI><CODE>user</CODE> - The string from the <CODE>originating-user-name</CODE>
1979  attribute</LI>
1980 <LI><CODE>title</CODE> - The string from the <CODE>job-name</CODE>
1981  attribute</LI>
1982 <LI><CODE>copies</CODE> - The numeric value from the <CODE>number-copies</CODE>
1983  attribute</LI>
1984 <LI><CODE>options</CODE> - String representations of the job template
1985  attributes, separated by spaces. Boolean attributes are provided as
1986  &quot;name&quot; for true values and &quot;noname&quot; for false values. All other
1987  attributes are provided as &quot;name=value&quot; for single-valued attributes
1988  and &quot;name=value1,value2,...,valueN&quot; for set attributes</LI>
1989 <LI><CODE>filename</CODE> - The request file</LI>
1990 </UL>
1991 <P>The<I> filename</I> argument is only provided to the first filter in
1992  the chain; all filters<B> must</B> be prepared to read the print file
1993  from the standard input if the<I> filename</I> argument is omitted.</P>
1994 <H3><A NAME="4_1_7">Copy Generation</A></H3>
1995 <P>The<I> copies</I> argument specifies the number of copies to produce
1996  of the input file. In general, you should only generate copies if the<I>
1997  filename</I> argument is supplied. The only exception to this are
1998  filters that produce device-independent PostScript output (without any
1999  printer commands from the printer's PPD file), since the PostScript
2000  filter <CODE>pstops</CODE> is responsible for copy generation.</P>
2001 <H3><A NAME="4_1_8">Environment Variables</A></H3>
2002 <P>Every filter receives a fixed set of environment variables that can
2003  be used by the filter:</P>
2004 <UL>
2005 <LI><CODE>CHARSET</CODE> - The character set used by the client for this
2006  print file</LI>
2007 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
2008  &quot;application/postscript&quot;</LI>
2009 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files</LI>
2010 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
2011  files</LI>
2012 <LI><CODE>DEVICE_URI</CODE> - The output device URI</LI>
2013 <LI><CODE>LANG</CODE> - The language used by the client for this print
2014  file</LI>
2015 <LI><CODE>PATH</CODE> - The execution path exported to the filter</LI>
2016 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file</LI>
2017 <LI><CODE>PRINTER</CODE> - The name of the printer queue</LI>
2018 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
2019  should use</LI>
2020 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
2021  &quot;CUPS/1.1&quot;</LI>
2022 <LI><CODE>TZ</CODE> - The local timezone</LI>
2023 <LI><CODE>USER</CODE> - The name of the current user</LI>
2024 </UL>
2025 <H2><A NAME="4_2">Dissecting the HP-GL/2 Filter</A></H2>
2026 <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
2027  complex program that converts HP-GL/2 files into device-independent
2028  PostScript output. Since it produces device-independent PostScript
2029  output, it does not need to handle copy generation or writing printer
2030  options from the printer's PPD file.</P>
2031 <H3><A NAME="4_2_1">Initializing the Filter</A></H3>
2032 <P>The first task of any filter is to ensure that the correct number of
2033  command-line arguments are present:</P>
2034 <UL>
2035 <PRE>
2036 if (argc &lt; 6 || argc &gt; 7)
2037 {
2038   fputs(&quot;ERROR: hpgltops job-id user title copies options [file]\n&quot;, stderr);
2039   return (1);
2040 }
2041 </PRE>
2042 </UL>
2043 <P>After this you open the print file or read from the standard input as
2044  needed:</P>
2045 <UL>
2046 <PRE>
2047 FILE *fp;
2048
2049 /*
2050  * If we have 7 arguments, print the file named on the command-line.
2051  * Otherwise, send stdin instead...
2052  */
2053
2054 if (argc == 6)
2055   fp = stdin;
2056 else
2057 {
2058  /*
2059   * Try to open the print file...
2060   */
2061
2062   if ((fp = fopen(argv[6], &quot;rb&quot;)) == NULL)
2063   {
2064     perror(&quot;ERROR: unable to open print file - &quot;);
2065     return (1);
2066   }
2067 }
2068 </PRE>
2069 </UL>
2070 <P>Once the print file has been opened, options can be processed using
2071  the<A HREF="#cupsParseOptions"> <CODE>cupsParseOptions()</CODE></A> and<A
2072 HREF="#cupsGetOption"> <CODE>cupsGetOption()</CODE></A> functions:</P>
2073 <UL>
2074 <PRE>
2075 int           num_options;
2076 cups_option_t *options;
2077 const char    *val;
2078
2079 /*
2080  * Process command-line options and write the prolog...
2081  */
2082
2083 options     = NULL;
2084 num_options = cupsParseOptions(argv[5], 0,
2085
2086 if ((val = cupsGetOption(&quot;blackplot&quot;, num_options, options)) != NULL)
2087   shading = 0;
2088
2089 if ((val = cupsGetOption(&quot;fitplot&quot;, num_options, options)) != NULL)
2090   FitPlot = 1;
2091
2092 if ((val = cupsGetOption(&quot;penwidth&quot;, num_options, options)) != NULL)
2093   PenWidth = (float)atoi(val) * 0.001f;
2094 </PRE>
2095 </UL>
2096 <P>After the options have been processed, the filter writes PostScript
2097  code to the standard output based on the print file, closes the print
2098  file (as needed), and returns 0 to the scheduler.</P>
2099 <H2><A NAME="4_3">PostScript Output</A></H2>
2100 <P>Filters that produce PostScript output must generate output
2101  conforming to the Adobe Document Structuring Conventions, 3.0. In
2102  general this means the beginning of each file must begin with:</P>
2103 <UL>
2104 <PRE>
2105 %!PS-Adobe-3.0
2106 %%BoundingBox: left bottom right top
2107 %%Pages: (atend)
2108 %%EndComments
2109 </PRE>
2110 </UL>
2111 <P>The<I> left</I>,<I> bottom</I>,<I> right</I>, and<I> top</I> values
2112  are integers in points from the lower-lefthand corner of the page.</P>
2113 <P>Pages must be surrounded by:</P>
2114 <UL>
2115 <PRE>
2116 %%Page: number number
2117 gsave
2118 ...
2119 grestore
2120 showpage
2121 </PRE>
2122 </UL>
2123 <P>And the end of each file must contain:</P>
2124 <UL>
2125 <PRE>
2126 %%Trailer
2127 %%Pages: number-pages
2128 %%EOF
2129 </PRE>
2130 </UL>
2131 <P>These comments allow the PostScript filter to correctly perform page
2132  accounting, copy generation, N-up printing, and so forth.</P>
2133 <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A>
2134 </H1>
2135 <P>This chapter discusses how to write a printer driver, which is a
2136  special filter program that converts CUPS raster data into the
2137  appropriate commands and data required for a printer.</P>
2138 <H2><A NAME="5_1">Overview</A></H2>
2139 <P>Raster printers utilitize PPD files that specify one or more
2140  device-specific filters that handle converting print files for the
2141  printer. The simplest raster printer drivers provide a single filter
2142  that converts CUPS raster data to the printer's native format.</P>
2143 <H3><A NAME="5_1_1">CUPS Raster Data</A></H3>
2144 <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists
2145  of a stream of raster page descriptions produced by one of the RIP
2146  filters, such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.</P>
2147 <P>Each page of data begins with a page dictionary structure called<A HREF="#cups_raster_header_t">
2148  <CODE>cups_raster_header_t</CODE></A>. This structure contains the
2149  colorspace, bits per color, media size, media type, hardware
2150  resolution, and so forth.</P>
2151 <P>After the page dictionary comes the page data which is a
2152  full-resolution, uncompressed bitmap representing the page in the
2153  printer's output colorspace.</P>
2154 <H3><A NAME="5_1_2">Page Accounting</A></H3>
2155 <P>Printer drivers must handle all page accounting. This means they must
2156  send &quot;PAGE:&quot; messages to the standard error file for each page (and in
2157  many cases, copy) sent to the printer.</P>
2158 <H3><A NAME="5_1_3">Color Management</A></H3>
2159 <P>Printer drivers can implement their color management via the <CODE>
2160 cupsColorProfile</CODE> attributes in the PPD file or internally in the
2161  driver from a device-independent colorspace. In general, color
2162  management performed by the RIP filters is more efficient than that
2163  performed inside printer drivers.</P>
2164 <P>For example, the <CODE>pstoraster</CODE> filter often only has to
2165  perform a color conversion once each time the color is used for
2166  multiple output pixels, while the raster filter must convert every
2167  pixel on the page.</P>
2168 <H3><A NAME="5_1_4">Device and Bitmap Variables</A></H3>
2169 <P>Besides the standard PostScript page device dictionary variables
2170  defined in the Adobe PostScript Level 3 reference manual, the CUPS
2171  filters support additional variables that are passed in the page device
2172  dictionary header for the page and in some cases control the type of
2173  raster data that is generated:
2174 <CENTER>
2175 <TABLE BORDER="1" WIDTH="90%">
2176 <TR><TH>Variable</TH><TH>Type</TH><TH>Description</TH></TR>
2177 <TR><TD>cupsWidth</TD><TD>read-only integer</TD><TD>Width of bitmap in
2178  pixels</TD></TR>
2179 <TR><TD>cupsHeight</TD><TD>read-only integer</TD><TD>Height of bitmap in
2180  pixels</TD></TR>
2181 <TR><TD>cupsMediaType</TD><TD>read-write integer</TD><TD>Device-specific
2182  media type code</TD></TR>
2183 <TR><TD>cupsBitsPerColor</TD><TD>read-write integer</TD><TD>Number of
2184  bits per color; 1, 2, 4, and 8 are currently supported</TD></TR>
2185 <TR><TD>cupsBitsPerPixel</TD><TD>read-only integer</TD><TD>Number of
2186  bits per pixel; 1 to 32</TD></TR>
2187 <TR><TD>cupsBytesPerLine</TD><TD>read-only integer</TD><TD>Number of
2188  bytes per line of raster graphics</TD></TR>
2189 <TR><TD>cupsColorOrder</TD><TD>read-write enum</TD><TD>The order of
2190  color values in the bitmap:
2191 <UL>
2192 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
2193 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
2194 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
2195 </UL>
2196 </TD></TR>
2197 <TR><TD>cupsColorSpace</TD><TD>read-write enum</TD><TD>The colorspace of
2198  the bitmap:
2199 <UL>
2200 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
2201 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
2202 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
2203 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
2204 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
2205 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
2206 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
2207 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
2208 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
2209 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2210  light cyan, light magenta</LI>
2211 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
2212  magenta, metallic cyan, black</LI>
2213 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
2214  magenta, metallic cyan, metallic grey (silver)</LI>
2215 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
2216  pigment)</LI>
2217 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
2218 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
2219 </UL>
2220 </TD></TR>
2221 <TR><TD>cupsCompression</TD><TD>read-write integer</TD><TD>
2222 Device-specific compression type code</TD></TR>
2223 <TR><TD>cupsRowCount</TD><TD>read-write integer</TD><TD>Device-specific
2224  row count value</TD></TR>
2225 <TR><TD>cupsRowFeed</TD><TD>read-write integer</TD><TD>Device-specific
2226  row feed value</TD></TR>
2227 <TR><TD>cupsRowStep</TD><TD>read-write integer</TD><TD>Device-specific
2228  row step value</TD></TR>
2229 </TABLE>
2230 </CENTER>
2231 </P>
2232 <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit
2233  per color are transmitted to the raster driver in KCMY colorspace; the
2234  driver is responsible for producing the correct separation of normal
2235  and light cyan and magenta inks.</P>
2236 <H2><A NAME="5_2">Dissecting the HP-PCL Driver</A></H2>
2237 <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>)
2238  converts bitmap data from the raster filters into HP-PCL commands for
2239  most PCL-compatible printers. The actual format of the raster data is
2240  controlled by the PPD file being used -<VAR> deskjet.ppd</VAR> or<VAR>
2241  laserjet.ppd</VAR>.</P>
2242 <H3><A NAME="5_2_1">PPD Files</A></H3>
2243 <P>PPD files play an important part of all raster printer drivers.
2244  Options defined in the PPD file contain PostScript commands that
2245  control the raster data that is sent to the printer driver.</P>
2246 <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, <CODE>
2247 InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, and <CODE>
2248 Resolution</CODE> options. Each option is shown using the standard PPD
2249  format:</P>
2250 <UL>
2251 <PRE>
2252 *OpenUI *PageSize/Media Size: PickOne
2253 *OrderDependency: 10 AnySetup *PageSize
2254 *DefaultPageSize: Letter
2255 *PageSize Letter/US Letter: &quot;&lt;&lt;
2256 /PageSize [612 792]
2257 /ImagingBBox null
2258 &gt;&gt; setpagedevice&quot;
2259 *End
2260 *PageSize Legal/US Legal: &quot;&lt;&lt;
2261 /PageSize [612 1008]
2262 /ImagingBBox null
2263 &gt;&gt; setpagedevice&quot;
2264 *End
2265 *PageSize A4/A4: &quot;&lt;&lt;
2266 /PageSize [595 842]
2267 /ImagingBBox null
2268 &gt;&gt; setpagedevice&quot;
2269 *End
2270 *CloseUI: *PageSize
2271 </PRE>
2272 </UL>
2273 <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
2274  name is the option with an asterisk (*) in front of it. The first name
2275  is usually followed by a slash (/) and a human-readable version of the
2276  option name.</P>
2277 <P>Every option<B> must</B> have a default value, specified using the <CODE>
2278 Default<I>Option</I></CODE> keyword.</P>
2279 <P>Each option begins with the option name followed by the computer and
2280  human-readable values. The PostScript commands follow these inside
2281  double quotes. PostScript commands can be provided on a single line:</P>
2282 <UL>
2283 <PRE>
2284 *PageSize A4/A4: &quot;&lt;&lt;/PageSize[595 842]/ImagingBBox null&gt;&gt; setpagedevice&quot;
2285 </PRE>
2286 </UL>
2287 <P>or broken down on separate lines using the <CODE>End</CODE> keyword
2288  to terminate them:</P>
2289 <UL>
2290 <PRE>
2291 *PageSize A4/A4: &quot;&lt;&lt;
2292 /PageSize [595 842]
2293 /ImagingBBox null
2294 &gt;&gt; setpagedevice&quot;
2295 *End
2296 </PRE>
2297 </UL>
2298 <P>The choice of the two formats is usually esthetic. However, each line
2299  in a PPD file must not exceed 255 characters, so if your PostScript
2300  commands are long you may need to break them up on separate lines.</P>
2301 <H3><A NAME="5_2_2">Reading Raster Data</A></H3>
2302 <P>As with any filter, your printer driver should handle raster data
2303  from a filename specified on the command-line or from the standard
2304  input. The<A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>
2305  function opens a raster stream for printing:</P>
2306 <UL>
2307 <PRE>
2308 int           fd;   /* File descriptor */
2309 cups_raster_t *ras; /* Raster stream for printing */
2310
2311
2312 /*
2313  * Check for valid arguments...
2314  */
2315
2316 if (argc &lt; 6 || argc &gt; 7)
2317 {
2318  /*
2319   * We don't have the correct number of arguments; write an error message
2320   * and return.
2321   */
2322
2323   fputs(&quot;ERROR: rastertopcl job-id user title copies options [file]\n&quot;, stderr);
2324   return (1);
2325 }
2326
2327 /*
2328  * Open the page stream...
2329  */
2330
2331 if (argc == 7)
2332 {
2333   if ((fd = open(argv[6], O_RDONLY)) == -1)
2334   {
2335     perror(&quot;ERROR: Unable to open raster file - &quot;);
2336     sleep(1);
2337     return (1);
2338   }
2339 }
2340 else
2341   fd = 0;
2342
2343 ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
2344 </PRE>
2345 </UL>
2346 <P>Once you have opened the raster stream you just need to read each
2347  page and print it:</P>
2348 <UL>
2349 <PRE>
2350 cups_raster_header_t header;
2351 int                  y;
2352 unsigned char        data[8192];
2353
2354 while (cupsRasterReadHeader(ras, &amp;header))
2355 {
2356   ... initialize the printer ...
2357   for (y = header.cupsHeight; y &gt; 0; y ++)
2358   {
2359     cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
2360     ... send raster line to printer ...
2361   }
2362 }
2363 </PRE>
2364 </UL>
2365 <P>After you have processed all pages, close the raster stream and
2366  return:</P>
2367 <UL>
2368 <PRE>
2369 cupsRasterClose(ras);
2370
2371 return (0);
2372 </PRE>
2373 </UL>
2374 <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
2375 <P>This chapter describes how to write a backend for CUPS. Backends
2376  communicate directly with printers and allow printer drivers and
2377  filters to send data using any type of connection transparently.</P>
2378 <H2><A NAME="6_1">Overview</A></H2>
2379 <P>Backends are special filters that communicate with printers directly.
2380  They are treated slightly differently than filters, however, and have
2381  some unique requirements.</P>
2382 <H3><A NAME="6_1_1">Security Considerations</A></H3>
2383 <P>Backends are run as the root user, so special care must be taken to
2384  avoid potential security violations. In particular, remember that a
2385  backend will be able to manipulate disk files, devices, and other
2386  resources that potentially could damage a system or printer.</P>
2387 <H3><A NAME="6_1_2">Command-Line Arguments</A></H3>
2388 <P>Besides the standard filter arguments, backends are also run with no
2389  arguments to get a list of available devices. This discovery process is
2390  described later in this chapter.</P>
2391 <H3><A NAME="6_1_3">Copy Generation</A></H3>
2392 <P>Like filters, backends should send multiple copies of the print file
2393  only if a filename is supplied on the command-line. Otherwise the
2394  backend should assume that the upstream filter has already added the
2395  necessary commands or data to produce the multiple copies.</P>
2396 <H3><A NAME="6_1_4">Page Accounting</A></H3>
2397 <P>Backend filters generally do not do page accounting, however they
2398  should at a minimum produce a single page message for each copy that is
2399  produced when a filename is present on the command-line. This is
2400  because the user selected &quot;raw&quot; printing and no other accounting
2401  information is possible.</P>
2402 <H3><A NAME="6_1_5">Exclusive Access</A></H3>
2403 <P>Backends that talk to local character or block devices should open
2404  the device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate
2405  with other printers defined for the same device.</P>
2406 <H3><A NAME="6_1_6">Retries</A></H3>
2407 <P>All backends<B> must</B> retry connections to the device. This
2408  includes backends that talk to local character or block devices, as the
2409  user may define more than one printer queue pointing at the same
2410  physical device.</P>
2411 <P>To prevent excess CPU utilitization, the backend should go to sleep
2412  for an amount of time between retries; the CUPS-supplied backends retry
2413  once every 30 seconds.</P>
2414 <H2><A NAME="6_2">Dissecting the Serial Port Backend</A></H2>
2415 <P>The serial port backend provides support for serial printers. Since
2416  it does everything a good backend needs to do, it provides an excellent
2417  example of what to do.</P>
2418 <H3><A NAME="6_2_1">Supporting Device Discovery</A></H3>
2419 <P>As previously noted, backends are special filter programs that talk
2420  to printer devices. Another task a backend must perform is to list the
2421  available devices it supports. The backend lists the available devices
2422  when no additioanl arguments are supplied on the command-line (i.e.
2423  just the command name...)</P>
2424 <P>The serial backend lists devices by looking at serial port files in
2425  the<VAR> /dev</VAR> directory, by consulting a hardware inventory
2426  (IRIX), and in some cases by trying to open the ports to see if they
2427  actually exist.</P>
2428 <P>Once it finds a serial port it writes a single line for each port to
2429  the standard error file. Each line looks like this:</P>
2430 <UL>
2431 <PRE>
2432 serial serial:/dev/ttyS0?baud=115200 &quot;Unknown&quot; &quot;Serial Port 1&quot;
2433 </PRE>
2434 </UL>
2435 <P>The first word &quot;serial&quot; is the<I> device class</I>; this identifies
2436  the class of device which can be used to categorize it in user
2437  interfaces. CUPS currently recognizes the following classes:</P>
2438 <UL>
2439 <LI>&quot;file&quot; - a disk file.</LI>
2440 <LI>&quot;direct&quot; - a parallel or fixed-rate serial data port, currently used
2441  for Centronics, IEEE-1284, and USB printer ports.</LI>
2442 <LI>&quot;serial&quot; - a variable-rate serial port.</LI>
2443 <LI>&quot;network&quot; - a network connection, typically via AppSocket, HTTP,
2444  IPP, LPD, or SMB/CIFS protocols.</LI>
2445 </UL>
2446 <P>After the device class is the<I> device URI</I>, in this case
2447  &quot;serial:/dev/ttyS0?baud=115200&quot;. This is the URI that should be used by
2448  the user to select this port. For serial ports, the &quot;baud=115200&quot;
2449  specifies the maximum baud rate supported by the port - the actual
2450  value will vary based on the speed the user selects for the printer.</P>
2451 <P>The last two strings are the model and description for the port. The
2452  &quot;Unknown&quot; string means that the printer model is unknown - some devices
2453  are able to provide a make and model such as &quot;HP DeskJet&quot; that allows
2454  users and software to choose an appropriate printer driver more easily.
2455  Both the model and description must be enclosed inside double quotes.</P>
2456 <H3><A NAME="6_2_2">Opening the Serial Port</A></H3>
2457 <P>As noted previously, all backends should open device files in
2458  exclusive mode, and retry as needed until the port is available. The
2459  serial port does this using a <CODE>do-while</CODE> loop:</P>
2460 <UL>
2461 <PRE>
2462 do
2463 {
2464   if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
2465   {
2466     if (errno == EBUSY)
2467     {
2468       fputs(&quot;INFO: Serial port busy; will retry in 30 seconds...\n&quot;, stderr);
2469       sleep(30);
2470     }
2471     else
2472     {
2473       perror(&quot;ERROR: Unable to open serial port device file&quot;);
2474       return (1);
2475     }
2476   }
2477 }
2478 while (fd &lt; 0);
2479 </PRE>
2480 </UL>
2481 <P>If the port is busy or in use by another process, the backend will go
2482  to sleep for 30 seconds and try again. If another error is detected a
2483  message is sent to the user and the backend aborts the print job until
2484  the problem can be corrected.</P>
2485 <H3><A NAME="6_2_3">Writing Data to the Port</A></H3>
2486 <P>Network and character devices pose an interesting problem when
2487  writing data to the port - they may not be able to write all of the
2488  bytes in your buffer before returning. To work around this problem you
2489  must loop until all bytes have been written:</P>
2490 <UL>
2491 <PRE>
2492 while (nbytes &gt; 0)
2493 {
2494   if ((wbytes = write(fd, bufptr, nbytes)) &lt; 0)
2495     if (errno == ENOTTY)
2496       wbytes = write(fd, bufptr, nbytes);
2497
2498   if (wbytes &lt; 0)
2499   {
2500     perror(&quot;ERROR: Unable to send print file to printer&quot;);
2501     break;
2502   }
2503
2504   nbytes -= wbytes;
2505   bufptr += wbytes;
2506 }
2507 </PRE>
2508 </UL>
2509 <P>The check for the <CODE>ENOTTY</CODE> error is needed on some
2510  platforms to clear an error from a previous <CODE>ioctl()</CODE> call.</P>
2511 <H3><A NAME="6_2_4">Finishing Up</A></H3>
2512 <P>Once you have sent the print file, return 0 if the file printed
2513  successfully or 1 if it did not. This will allow the scheduler to stop
2514  the print job if there is a device error, preserving the print job for
2515  later printing once the problem has been corrected.</P>
2516 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
2517 <H2 ALIGN="CENTER"><A NAME="7_1">Common UNIX Printing System License
2518  Agreement</A></H2>
2519 <P ALIGN="CENTER">Copyright 1997-2002 by Easy Software Products
2520 <BR> 44141 AIRPORT VIEW DR STE 204
2521 <BR> HOLLYWOOD, MARYLAND 20636-3111 USA
2522 <BR>
2523 <BR> Voice: +1.301.373.9600
2524 <BR> Email:<A HREF="mailto:cups-info@cups.org"> cups-info@cups.org</A>
2525 <BR> WWW:<A HREF="http://www.cups.org"> http://www.cups.org</A></P>
2526 <H3><A NAME="7_1_1">Introduction</A></H3>
2527 <P>The Common UNIX Printing System<SUP>TM</SUP>, (&quot;CUPS<SUP>TM</SUP>&quot;),
2528  is provided under the GNU General Public License (&quot;GPL&quot;) and GNU
2529  Library General Public License (&quot;LGPL&quot;), Version 2, with exceptions for
2530  Apple operating systems. A copy of the exceptions and licenses follow
2531  this introduction.</P>
2532 <P>The GNU LGPL applies to the CUPS API library, located in the &quot;cups&quot;
2533  subdirectory of the CUPS source distribution and in the
2534  &quot;/usr/include/cups&quot; directory and &quot;libcups.a&quot;, &quot;libcups_s.a&quot;,
2535  &quot;libcups.sl&quot;, &quot;libcups.so&quot;, or &quot;libcups.dylib&quot; files in the binary
2536  distributions.</P>
2537 <P>The GNU GPL applies to the remainder of the CUPS distribution,
2538  including the &quot;pstoraster&quot; filter which is based upon GNU Ghostscript
2539  5.50 and the &quot;pdftops&quot; filter which is based upon Xpdf 0.93a.</P>
2540 <P>For those not familiar with the GNU GPL, the license basically allows
2541  you to:</P>
2542 <UL>
2543 <LI>Use the CUPS software at no charge.</LI>
2544 <LI>Distribute verbatim copies of the software in source or binary form.</LI>
2545 <LI>Sell verbatim copies of the software for a media fee, or sell
2546  support for the software.</LI>
2547 <LI>Distribute or sell printer drivers and filters that use CUPS so long
2548  as source code is made available under the GPL.</LI>
2549 </UL>
2550 <P>What this license<B> does not</B> allow you to do is make changes or
2551  add features to CUPS and then sell a binary distribution without source
2552  code. You must provide source for any new drivers, changes, or
2553  additions to the software, and all code must be provided under the GPL
2554  or LGPL as appropriate. The only exceptions to this are the portions of
2555  the CUPS software covered by the Apple operating system license
2556  exceptions outlined later in this license agreement.</P>
2557 <P>The GNU LGPL relaxes the &quot;link-to&quot; restriction, allowing you to
2558  develop applications that use the CUPS API library under other licenses
2559  and/or conditions as appropriate for your application.</P>
2560 <H3><A NAME="7_1_2">Apple Operating System Development License Exception</A>
2561 </H3>
2562 <P>In addition, as the copyright holder of CUPS, Easy Software Products
2563  grants the following special exception:<BLOCKQUOTE>Software that is
2564  developed by any person or entity for an Apple Operating System (&quot;Apple
2565  OS-Developed Software&quot;), including but not limited to Apple and third
2566  party printer drivers, filters, and backends for an Apple Operating
2567  System, that is linked to the CUPS imaging library or based on any
2568  sample filters or backends provided with CUPS shall not be considered
2569  to be a derivative work or collective work based on the CUPS program
2570  and is exempt from the mandatory source code release clauses of the GNU
2571  GPL. You may therefore distribute linked combinations of the CUPS
2572  imaging library with Apple OS-Developed Software without releasing the
2573  source code of the Apple OS-Developed Software. You may also use sample
2574  filters and backends provided with CUPS to develop Apple OS-Developed
2575  Software without releasing the source code of the Apple OS-Developed
2576  Software.</BLOCKQUOTE></P>
2577 <P>An Apple Operating System means any operating system software
2578  developed and/or marketed by Apple Computer, Inc., including but not
2579  limited to all existing releases and versions of Apple's Darwin, Mac OS
2580  X, and Mac OS X Server products and all follow-on releases and future
2581  versions thereof.</P>
2582 <P>This exception is only available for Apple OS-Developed Software and
2583  does not apply to software that is distributed for use on other
2584  operating systems.</P>
2585 <P>All CUPS software that falls under this license exception have the
2586  following text at the top of each source file:<BLOCKQUOTE>This file is
2587  subject to the Apple OS-Developed Software exception.</BLOCKQUOTE></P>
2588 <H3><A NAME="7_1_3">Trademarks</A></H3>
2589 <P>Easy Software Products has trademarked the Common UNIX Printing
2590  System, CUPS, and CUPS logo. These names and logos may be used freely
2591  in any direct port or binary distribution of CUPS. To use them in
2592  derivative products, please contract Easy Software Products for written
2593  permission. Our intention is to protect the value of these trademarks
2594  and ensure that any derivative product meets the same high-quality
2595  standards as the original.</P>
2596 <H3><A NAME="7_1_4">Binary Distribution Rights</A></H3>
2597 <P>Easy Software Products also sells rights to the CUPS source code
2598  under a binary distribution license for vendors that are unable to
2599  release source code for their drivers, additions, and modifications to
2600  CUPS under the GNU GPL and LGPL. For information please contact us at
2601  the address shown above.</P>
2602 <P>The Common UNIX Printing System provides a &quot;pstoraster&quot; filter that
2603  utilizes the GNU GhostScript 5.50 core to convert PostScript files into
2604  a stream of raster images. For binary distribution licensing of this
2605  software, please contact:<BLOCKQUOTE> Miles Jones
2606 <BR> Director of Marketing
2607 <BR> Artifex Software Inc.
2608 <BR> 454 Las Gallinas Ave., Suite 108
2609 <BR> San Rafael, CA 94903 USA
2610 <BR> Voice: +1.415.492.9861
2611 <BR> Fax: +1.415.492.9862
2612 <BR> EMail:<A HREF="mailto:info@arsoft.com"> info@arsoft.com</A></BLOCKQUOTE>
2613 </P>
2614 <P>The &quot;pdftops&quot; filter is based on the Xpdf 0.93a software. For binary
2615  distribution licensing of this software, please contact:<BLOCKQUOTE>
2616  Derek B. Noonburg
2617 <BR> Email:<A HREF="mailto:derekn@foolabs.com"> derekn@foolabs.com</A>
2618 <BR> WWW:<A HREF="http://www.foolabs.com/xpdf/">
2619  http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P>
2620 <H3><A NAME="7_1_5">Support</A></H3>
2621 <P>Easy Software Products sells software support for CUPS as well as a
2622  commercial printing product based on CUPS called ESP Print Pro. You can
2623  find out more at our web site:</P>
2624 <UL>
2625 <PRE>
2626 <A HREF="http://www.easysw.com">http://www.easysw.com</A>
2627 </PRE>
2628 </UL>
2629
2630 <!-- NEW PAGE -->
2631 <H2><A NAME="7_2">GNU GENERAL PUBLIC LICENSE</A></H2>
2632 <P>Version 2, June 1991</P>
2633 <PRE>
2634 Copyright 1989, 1991 Free Software Foundation, Inc.
2635 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2636
2637 Everyone is permitted to copy and distribute verbatim
2638 copies of this license document, but changing it is not allowed.
2639 </PRE>
2640 <PRE>
2641
2642 </PRE>
2643 <H4>Preamble</H4>
2644 <P>The licenses for most software are designed to take away your freedom
2645  to share and change it. By contrast, the GNU General Public License is
2646  intended to guarantee your freedom to share and change free
2647  software--to make sure the software is free for all its users. This
2648  General Public License applies to most of the Free Software
2649  Foundation's software and to any other program whose authors commit to
2650  using it. (Some other Free Software Foundation software is covered by
2651  the GNU Library General Public License instead.) You can apply it to
2652  your programs, too.</P>
2653 <P>When we speak of free software, we are referring to freedom, not
2654  price. Our General Public Licenses are designed to make sure that you
2655  have the freedom to distribute copies of free software (and charge for
2656  this service if you wish), that you receive source code or can get it
2657  if you want it, that you can change the software or use pieces of it in
2658  new free programs; and that you know you can do these things.</P>
2659 <P>To protect your rights, we need to make restrictions that forbid
2660  anyone to deny you these rights or to ask you to surrender the rights.
2661  These restrictions translate to certain responsibilities for you if you
2662  distribute copies of the software, or if you modify it.</P>
2663 <P>For example, if you distribute copies of such a program, whether
2664  gratis or for a fee, you must give the recipients all the rights that
2665  you have. You must make sure that they, too, receive or can get the
2666  source code. And you must show them these terms so they know their
2667  rights.</P>
2668 <P>We protect your rights with two steps: (1) copyright the software,
2669  and (2) offer you this license which gives you legal permission to
2670  copy, distribute and/or modify the software.</P>
2671 <P>Also, for each author's protection and ours, we want to make certain
2672  that everyone understands that there is no warranty for this free
2673  software. If the software is modified by someone else and passed on, we
2674  want its recipients to know that what they have is not the original, so
2675  that any problems introduced by others will not reflect on the original
2676  authors' reputations.</P>
2677 <P>Finally, any free program is threatened constantly by software
2678  patents. We wish to avoid the danger that redistributors of a free
2679  program will individually obtain patent licenses, in effect making the
2680  program proprietary. To prevent this, we have made it clear that any
2681  patent must be licensed for everyone's free use or not licensed at all.</P>
2682 <P>The precise terms and conditions for copying, distribution and
2683  modification follow.</P>
2684 <H4>GNU GENERAL PUBLIC LICENSE
2685 <BR> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2686 <OL START="0">
2687 <LI>This License applies to any program or other work which contains a
2688  notice placed by the copyright holder saying it may be distributed
2689  under the terms of this General Public License. The &quot;Program&quot;, below,
2690  refers to any such program or work, and a &quot;work based on the Program&quot;
2691  means either the Program or any derivative work under copyright law:
2692  that is to say, a work containing the Program or a portion of it,
2693  either verbatim or with modifications and/or translated into another
2694  language. (Hereinafter, translation is included without limitation in
2695  the term &quot;modification&quot;.) Each licensee is addressed as &quot;you&quot;.</LI>
2696 <P>Activities other than copying, distribution and modification are not
2697  covered by this License; they are outside its scope. The act of running
2698  the Program is not restricted, and the output from the Program is
2699  covered only if its contents constitute a work based on the Program
2700  (independent of having been made by running the Program). Whether that
2701  is true depends on what the Program does.</P>
2702 <LI>You may copy and distribute verbatim copies of the Program's source
2703  code as you receive it, in any medium, provided that you conspicuously
2704  and appropriately publish on each copy an appropriate copyright notice
2705  and disclaimer of warranty; keep intact all the notices that refer to
2706  this License and to the absence of any warranty; and give any other
2707  recipients of the Program a copy of this License along with the
2708  Program.</LI>
2709 <P>You may charge a fee for the physical act of transferring a copy, and
2710  you may at your option offer warranty protection in exchange for a fee.</P>
2711 <LI>You may modify your copy or copies of the Program or any portion of
2712  it, thus forming a work based on the Program, and copy and distribute
2713  such modifications or work under the terms of Section 1 above, provided
2714  that you also meet all of these conditions:
2715 <OL TYPE="a">
2716 <LI>You must cause the modified files to carry prominent notices stating
2717  that you changed the files and the date of any change.</LI>
2718 <LI>You must cause any work that you distribute or publish, that in
2719  whole or in part contains or is derived from the Program or any part
2720  thereof, to be licensed as a whole at no charge to all third parties
2721  under the terms of this License.</LI>
2722 <LI>if the modified program normally reads commands interactively when
2723  run, you must cause it, when started running for such interactive use
2724  in the most ordinary way, to print or display an announcement including
2725  an appropriate copyright notice and a notice that there is no warranty
2726  (or else, saying that you provide a warranty) and that users may
2727  redistribute the program under these conditions, and telling the user
2728  how to view a copy of this License. (Exception: if the Program itself
2729  is interactive but does not normally print such an announcement, your
2730  work based on the Program is not required to print an announcement.)</LI>
2731 </OL>
2732 </LI>
2733 <P>These requirements apply to the modified work as a whole. If
2734  identifiable sections of that work are not derived from the Program,
2735  and can be reasonably considered independent and separate works in
2736  themselves, then this License, and its terms, do not apply to those
2737  sections when you distribute them as separate works. But when you
2738  distribute the same sections as part of a whole which is a work based
2739  on the Program, the distribution of the whole must be on the terms of
2740  this License, whose permissions for other licensees extend to the
2741  entire whole, and thus to each and every part regardless of who wrote
2742  it.</P>
2743 <P>Thus, it is not the intent of this section to claim rights or contest
2744  your rights to work written entirely by you; rather, the intent is to
2745  exercise the right to control the distribution of derivative or
2746  collective works based on the Program.</P>
2747 <P>In addition, mere aggregation of another work not based on the
2748  Program with the Program (or with a work based on the Program) on a
2749  volume of a storage or distribution medium does not bring the other
2750  work under the scope of this License.</P>
2751 <LI>You may copy and distribute the Program (or a work based on it,
2752  under Section 2) in object code or executable form under the terms of
2753  Sections 1 and 2 above provided that you also do one of the following:
2754 <OL TYPE="a">
2755 <LI>Accompany it with the complete corresponding machine-readable source
2756  code, which must be distributed under the terms of Sections 1 and 2
2757  above on a medium customarily used for software interchange; or,</LI>
2758 <LI>Accompany it with a written offer, valid for at least three years,
2759  to give any third party, for a charge no more than your cost of
2760  physically performing source distribution, a complete machine-readable
2761  copy of the corresponding source code, to be distributed under the
2762  terms of Sections 1 and 2 above on a medium customarily used for
2763  software interchange; or,</LI>
2764 <LI>Accompany it with the information you received as to the offer to
2765  distribute corresponding source code. (This alternative is allowed only
2766  for noncommercial distribution and only if you received the program in
2767  object code or executable form with such an offer, in accord with
2768  Subsection b above.)</LI>
2769 </OL>
2770 </LI>
2771 <P>The source code for a work means the preferred form of the work for
2772  making modifications to it. For an executable work, complete source
2773  code means all the source code for all modules it contains, plus any
2774  associated interface definition files, plus the scripts used to control
2775  compilation and installation of the executable. However, as a special
2776  exception, the source code distributed need not include anything that
2777  is normally distributed (in either source or binary form) with the
2778  major components (compiler, kernel, and so on) of the operating system
2779  on which the executable runs, unless that component itself accompanies
2780  the executable.</P>
2781 <P>If distribution of executable or object code is made by offering
2782  access to copy from a designated place, then offering equivalent access
2783  to copy the source code from the same place counts as distribution of
2784  the source code, even though third parties are not compelled to copy
2785  the source along with the object code.</P>
2786 <LI>You may not copy, modify, sublicense, or distribute the Program
2787  except as expressly provided under this License. Any attempt otherwise
2788  to copy, modify, sublicense or distribute the Program is void, and will
2789  automatically terminate your rights under this License. However,
2790  parties who have received copies, or rights, from you under this
2791  License will not have their licenses terminated so long as such parties
2792  remain in full compliance.</LI>
2793 <LI>You are not required to accept this License, since you have not
2794  signed it. However, nothing else grants you permission to modify or
2795  distribute the Program or its derivative works. These actions are
2796  prohibited by law if you do not accept this License. Therefore, by
2797  modifying or distributing the Program (or any work based on the
2798  Program), you indicate your acceptance of this License to do so, and
2799  all its terms and conditions for copying, distributing or modifying the
2800  Program or works based on it.</LI>
2801 <LI>Each time you redistribute the Program (or any work based on the
2802  Program), the recipient automatically receives a license from the
2803  original licensor to copy, distribute or modify the Program subject to
2804  these terms and conditions. You may not impose any further restrictions
2805  on the recipients' exercise of the rights granted herein. You are not
2806  responsible for enforcing compliance by third parties to this License.</LI>
2807 <LI>If, as a consequence of a court judgment or allegation of patent
2808  infringement or for any other reason (not limited to patent issues),
2809  conditions are imposed on you (whether by court order, agreement or
2810  otherwise) that contradict the conditions of this License, they do not
2811  excuse you from the conditions of this License. If you cannot
2812  distribute so as to satisfy simultaneously your obligations under this
2813  License and any other pertinent obligations, then as a consequence you
2814  may not distribute the Program at all. For example, if a patent license
2815  would not permit royalty-free redistribution of the Program by all
2816  those who receive copies directly or indirectly through you, then the
2817  only way you could satisfy both it and this License would be to refrain
2818  entirely from distribution of the Program.</LI>
2819 <P>If any portion of this section is held invalid or unenforceable under
2820  any particular circumstance, the balance of the section is intended to
2821  apply and the section as a whole is intended to apply in other
2822  circumstances.</P>
2823 <P>It is not the purpose of this section to induce you to infringe any
2824  patents or other property right claims or to contest validity of any
2825  such claims; this section has the sole purpose of protecting the
2826  integrity of the free software distribution system, which is
2827  implemented by public license practices. Many people have made generous
2828  contributions to the wide range of software distributed through that
2829  system in reliance on consistent application of that system; it is up
2830  to the author/donor to decide if he or she is willing to distribute
2831  software through any other system and a licensee cannot impose that
2832  choice.</P>
2833 <P>This section is intended to make thoroughly clear what is believed to
2834  be a consequence of the rest of this License.</P>
2835 <LI>If the distribution and/or use of the Program is restricted in
2836  certain countries either by patents or by copyrighted interfaces, the
2837  original copyright holder who places the Program under this License may
2838  add an explicit geographical distribution limitation excluding those
2839  countries, so that distribution is permitted only in or among countries
2840  not thus excluded. In such case, this License incorporates the
2841  limitation as if written in the body of this License.</LI>
2842 <LI>The Free Software Foundation may publish revised and/or new versions
2843  of the General Public License from time to time. Such new versions will
2844  be similar in spirit to the present version, but may differ in detail
2845  to address new problems or concerns.</LI>
2846 <P>Each version is given a distinguishing version number. If the Program
2847  specifies a version number of this License which applies to it and &quot;any
2848  later version&quot;, you have the option of following the terms and
2849  conditions either of that version or of any later version published by
2850  the Free Software Foundation. If the Program does not specify a version
2851  number of this License, you may choose any version ever published by
2852  the Free Software Foundation.</P>
2853 <LI>If you wish to incorporate parts of the Program into other free
2854  programs whose distribution conditions are different, write to the
2855  author to ask for permission. For software which is copyrighted by the
2856  Free Software Foundation, write to the Free Software Foundation; we
2857  sometimes make exceptions for this. Our decision will be guided by the
2858  two goals of preserving the free status of all derivatives of our free
2859  software and of promoting the sharing and reuse of software generally.</LI>
2860 </OL>
2861 <H4>NO WARRANTY</H4>
2862 <OL START="11">
2863 <LI>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2864  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2865  OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2866  PROVIDE THE PROGRAM &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER
2867  EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
2868  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
2869  ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
2870  YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
2871  NECESSARY SERVICING, REPAIR OR CORRECTION.</LI>
2872 <LI>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
2873  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
2874  AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
2875  FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
2876  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
2877  PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
2878  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
2879  FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
2880  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
2881  DAMAGES.</LI>
2882 </OL>
2883 <H4>END OF TERMS AND CONDITIONS</H4>
2884
2885 <!-- NEW PAGE -->
2886 <H2><A NAME="7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2>
2887 <P>Version 2, June 1991</P>
2888 <PRE>
2889 Copyright (C) 1991 Free Software Foundation, Inc.
2890 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
2891 Everyone is permitted to copy and distribute verbatim copies
2892 of this license document, but changing it is not allowed.
2893
2894 [This is the first released version of the library GPL.  It is
2895  numbered 2 because it goes with version 2 of the ordinary GPL.]
2896 </PRE>
2897 <H4>Preamble</H4>
2898 <P>The licenses for most software are designed to take away your freedom
2899  to share and change it. By contrast, the GNU General Public Licenses
2900  are intended to guarantee your freedom to share and change free
2901  software--to make sure the software is free for all its users.</P>
2902 <P>This license, the Library General Public License, applies to some
2903  specially designated Free Software Foundation software, and to any
2904  other libraries whose authors decide to use it. You can use it for your
2905  libraries, too.</P>
2906 <P>When we speak of free software, we are referring to freedom, not
2907  price. Our General Public Licenses are designed to make sure that you
2908  have the freedom to distribute copies of free software (and charge for
2909  this service if you wish), that you receive source code or can get it
2910  if you want it, that you can change the software or use pieces of it in
2911  new free programs; and that you know you can do these things.</P>
2912 <P>To protect your rights, we need to make restrictions that forbid
2913  anyone to deny you these rights or to ask you to surrender the rights.
2914  These restrictions translate to certain responsibilities for you if you
2915  distribute copies of the library, or if you modify it.</P>
2916 <P>For example, if you distribute copies of the library, whether gratis
2917  or for a fee, you must give the recipients all the rights that we gave
2918  you. You must make sure that they, too, receive or can get the source
2919  code. If you link a program with the library, you must provide complete
2920  object files to the recipients so that they can relink them with the
2921  library, after making changes to the library and recompiling it. And
2922  you must show them these terms so they know their rights.</P>
2923 <P>Our method of protecting your rights has two steps: (1) copyright the
2924  library, and (2) offer you this license which gives you legal
2925  permission to copy, distribute and/or modify the library.</P>
2926 <P>Also, for each distributor's protection, we want to make certain that
2927  everyone understands that there is no warranty for this free library.
2928  If the library is modified by someone else and passed on, we want its
2929  recipients to know that what they have is not the original version, so
2930  that any problems introduced by others will not reflect on the original
2931  authors' reputations.</P>
2932 <P>Finally, any free program is threatened constantly by software
2933  patents. We wish to avoid the danger that companies distributing free
2934  software will individually obtain patent licenses, thus in effect
2935  transforming the program into proprietary software. To prevent this, we
2936  have made it clear that any patent must be licensed for everyone's free
2937  use or not licensed at all.</P>
2938 <P>Most GNU software, including some libraries, is covered by the
2939  ordinary GNU General Public License, which was designed for utility
2940  programs. This license, the GNU Library General Public License, applies
2941  to certain designated libraries. This license is quite different from
2942  the ordinary one; be sure to read it in full, and don't assume that
2943  anything in it is the same as in the ordinary license.</P>
2944 <P>The reason we have a separate public license for some libraries is
2945  that they blur the distinction we usually make between modifying or
2946  adding to a program and simply using it. Linking a program with a
2947  library, without changing the library, is in some sense simply using
2948  the library, and is analogous to running a utility program or
2949  application program. However, in a textual and legal sense, the linked
2950  executable is a combined work, a derivative of the original library,
2951  and the ordinary General Public License treats it as such.</P>
2952 <P>Because of this blurred distinction, using the ordinary General
2953  Public License for libraries did not effectively promote software
2954  sharing, because most developers did not use the libraries. We
2955  concluded that weaker conditions might promote sharing better.</P>
2956 <P>However, unrestricted linking of non-free programs would deprive the
2957  users of those programs of all benefit from the free status of the
2958  libraries themselves. This Library General Public License is intended
2959  to permit developers of non-free programs to use free libraries, while
2960  preserving your freedom as a user of such programs to change the free
2961  libraries that are incorporated in them. (We have not seen how to
2962  achieve this as regards changes in header files, but we have achieved
2963  it as regards changes in the actual functions of the Library.) The hope
2964  is that this will lead to faster development of free libraries.</P>
2965 <P>The precise terms and conditions for copying, distribution and
2966  modification follow. Pay close attention to the difference between a
2967  &quot;work based on the library&quot; and a &quot;work that uses the library&quot;. The
2968  former contains code derived from the library, while the latter only
2969  works together with the library.</P>
2970 <P>Note that it is possible for a library to be covered by the ordinary
2971  General Public License rather than by this special one.</P>
2972 <H4>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2973 <P><STRONG>0.</STRONG> This License Agreement applies to any software
2974  library which contains a notice placed by the copyright holder or other
2975  authorized party saying it may be distributed under the terms of this
2976  Library General Public License (also called &quot;this License&quot;). Each
2977  licensee is addressed as &quot;you&quot;.</P>
2978 <P>A &quot;library&quot; means a collection of software functions and/or data
2979  prepared so as to be conveniently linked with application programs
2980  (which use some of those functions and data) to form executables.</P>
2981 <P>The &quot;Library&quot;, below, refers to any such software library or work
2982  which has been distributed under these terms. A &quot;work based on the
2983  Library&quot; means either the Library or any derivative work under
2984  copyright law: that is to say, a work containing the Library or a
2985  portion of it, either verbatim or with modifications and/or translated
2986  straightforwardly into another language. (Hereinafter, translation is
2987  included without limitation in the term &quot;modification&quot;.)</P>
2988 <P>&quot;Source code&quot; for a work means the preferred form of the work for
2989  making modifications to it. For a library, complete source code means
2990  all the source code for all modules it contains, plus any associated
2991  interface definition files, plus the scripts used to control
2992  compilation and installation of the library.</P>
2993 <P>Activities other than copying, distribution and modification are not
2994  covered by this License; they are outside its scope. The act of running
2995  a program using the Library is not restricted, and output from such a
2996  program is covered only if its contents constitute a work based on the
2997  Library (independent of the use of the Library in a tool for writing
2998  it). Whether that is true depends on what the Library does and what the
2999  program that uses the Library does.</P>
3000 <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
3001  the Library's complete source code as you receive it, in any medium,
3002  provided that you conspicuously and appropriately publish on each copy
3003  an appropriate copyright notice and disclaimer of warranty; keep intact
3004  all the notices that refer to this License and to the absence of any
3005  warranty; and distribute a copy of this License along with the Library.</P>
3006 <P>You may charge a fee for the physical act of transferring a copy, and
3007  you may at your option offer warranty protection in exchange for a fee.</P>
3008 <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library
3009  or any portion of it, thus forming a work based on the Library, and
3010  copy and distribute such modifications or work under the terms of
3011  Section 1 above, provided that you also meet all of these conditions:</P>
3012 <OL TYPE="a">
3013 <LI>The modified work must itself be a software library.</LI>
3014 <P></P>
3015 <LI>You must cause the files modified to carry prominent notices stating
3016  that you changed the files and the date of any change.</LI>
3017 <P></P>
3018 <LI>You must cause the whole of the work to be licensed at no charge to
3019  all third parties under the terms of this License.</LI>
3020 <P></P>
3021 <LI>If a facility in the modified Library refers to a function or a
3022  table of data to be supplied by an application program that uses the
3023  facility, other than as an argument passed when the facility is
3024  invoked, then you must make a good faith effort to ensure that, in the
3025  event an application does not supply such function or table, the
3026  facility still operates, and performs whatever part of its purpose
3027  remains meaningful.</LI>
3028 <P>(For example, a function in a library to compute square roots has a
3029  purpose that is entirely well-defined independent of the application.
3030  Therefore, Subsection 2d requires that any application-supplied
3031  function or table used by this function must be optional: if the
3032  application does not supply it, the square root function must still
3033  compute square roots.)</P>
3034 </OL>
3035 <P>These requirements apply to the modified work as a whole. If
3036  identifiable sections of that work are not derived from the Library,
3037  and can be reasonably considered independent and separate works in
3038  themselves, then this License, and its terms, do not apply to those
3039  sections when you distribute them as separate works. But when you
3040  distribute the same sections as part of a whole which is a work based
3041  on the Library, the distribution of the whole must be on the terms of
3042  this License, whose permissions for other licensees extend to the
3043  entire whole, and thus to each and every part regardless of who wrote
3044  it.</P>
3045 <P>Thus, it is not the intent of this section to claim rights or contest
3046  your rights to work written entirely by you; rather, the intent is to
3047  exercise the right to control the distribution of derivative or
3048  collective works based on the Library.</P>
3049 <P>In addition, mere aggregation of another work not based on the
3050  Library with the Library (or with a work based on the Library) on a
3051  volume of a storage or distribution medium does not bring the other
3052  work under the scope of this License.</P>
3053 <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
3054  GNU General Public License instead of this License to a given copy of
3055  the Library. To do this, you must alter all the notices that refer to
3056  this License, so that they refer to the ordinary GNU General Public
3057  License, version 2, instead of to this License. (If a newer version
3058  than version 2 of the ordinary GNU General Public License has appeared,
3059  then you can specify that version instead if you wish.) Do not make any
3060  other change in these notices.</P>
3061 <P>Once this change is made in a given copy, it is irreversible for that
3062  copy, so the ordinary GNU General Public License applies to all
3063  subsequent copies and derivative works made from that copy.</P>
3064 <P>This option is useful when you wish to copy part of the code of the
3065  Library into a program that is not a library.</P>
3066 <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
3067  portion or derivative of it, under Section 2) in object code or
3068  executable form under the terms of Sections 1 and 2 above provided that
3069  you accompany it with the complete corresponding machine-readable
3070  source code, which must be distributed under the terms of Sections 1
3071  and 2 above on a medium customarily used for software interchange.</P>
3072 <P>If distribution of object code is made by offering access to copy
3073  from a designated place, then offering equivalent access to copy the
3074  source code from the same place satisfies the requirement to distribute
3075  the source code, even though third parties are not compelled to copy
3076  the source along with the object code.</P>
3077 <P><STRONG>5.</STRONG> A program that contains no derivative of any
3078  portion of the Library, but is designed to work with the Library by
3079  being compiled or linked with it, is called a &quot;work that uses the
3080  Library&quot;. Such a work, in isolation, is not a derivative work of the
3081  Library, and therefore falls outside the scope of this License.</P>
3082 <P>However, linking a &quot;work that uses the Library&quot; with the Library
3083  creates an executable that is a derivative of the Library (because it
3084  contains portions of the Library), rather than a &quot;work that uses the
3085  library&quot;. The executable is therefore covered by this License. Section
3086  6 states terms for distribution of such executables.</P>
3087 <P>When a &quot;work that uses the Library&quot; uses material from a header file
3088  that is part of the Library, the object code for the work may be a
3089  derivative work of the Library even though the source code is not.
3090  Whether this is true is especially significant if the work can be
3091  linked without the Library, or if the work is itself a library. The
3092  threshold for this to be true is not precisely defined by law.</P>
3093 <P>If such an object file uses only numerical parameters, data structure
3094  layouts and accessors, and small macros and small inline functions (ten
3095  lines or less in length), then the use of the object file is
3096  unrestricted, regardless of whether it is legally a derivative work.
3097  (Executables containing this object code plus portions of the Library
3098  will still fall under Section 6.)</P>
3099 <P>Otherwise, if the work is a derivative of the Library, you may
3100  distribute the object code for the work under the terms of Section 6.
3101  Any executables containing that work also fall under Section 6, whether
3102  or not they are linked directly with the Library itself.</P>
3103 <P><STRONG>6.</STRONG> As an exception to the Sections above, you may
3104  also compile or link a &quot;work that uses the Library&quot; with the Library to
3105  produce a work containing portions of the Library, and distribute that
3106  work under terms of your choice, provided that the terms permit
3107  modification of the work for the customer's own use and reverse
3108  engineering for debugging such modifications.</P>
3109 <P>You must give prominent notice with each copy of the work that the
3110  Library is used in it and that the Library and its use are covered by
3111  this License. You must supply a copy of this License. If the work
3112  during execution displays copyright notices, you must include the
3113  copyright notice for the Library among them, as well as a reference
3114  directing the user to the copy of this License. Also, you must do one
3115  of these things:</P>
3116 <OL TYPE="a">
3117 <LI>Accompany the work with the complete corresponding machine-readable
3118  source code for the Library including whatever changes were used in the
3119  work (which must be distributed under Sections 1 and 2 above); and, if
3120  the work is an executable linked with the Library, with the complete
3121  machine-readable &quot;work that uses the Library&quot;, as object code and/or
3122  source code, so that the user can modify the Library and then relink to
3123  produce a modified executable containing the modified Library. (It is
3124  understood that the user who changes the contents of definitions files
3125  in the Library will not necessarily be able to recompile the
3126  application to use the modified definitions.)</LI>
3127 <P></P>
3128 <LI>Accompany the work with a written offer, valid for at least three
3129  years, to give the same user the materials specified in Subsection 6a,
3130  above, for a charge no more than the cost of performing this
3131  distribution.</LI>
3132 <P></P>
3133 <LI>If distribution of the work is made by offering access to copy from
3134  a designated place, offer equivalent access to copy the above specified
3135  materials from the same place.</LI>
3136 <P></P>
3137 <LI>Verify that the user has already received a copy of these materials
3138  or that you have already sent this user a copy.</LI>
3139 </OL>
3140 <P>For an executable, the required form of the &quot;work that uses the
3141  Library&quot; must include any data and utility programs needed for
3142  reproducing the executable from it. However, as a special exception,
3143  the source code distributed need not include anything that is normally
3144  distributed (in either source or binary form) with the major components
3145  (compiler, kernel, and so on) of the operating system on which the
3146  executable runs, unless that component itself accompanies the
3147  executable.</P>
3148 <P>It may happen that this requirement contradicts the license
3149  restrictions of other proprietary libraries that do not normally
3150  accompany the operating system. Such a contradiction means you cannot
3151  use both them and the Library together in an executable that you
3152  distribute.</P>
3153 <P><STRONG>7.</STRONG> You may place library facilities that are a work
3154  based on the Library side-by-side in a single library together with
3155  other library facilities not covered by this License, and distribute
3156  such a combined library, provided that the separate distribution of the
3157  work based on the Library and of the other library facilities is
3158  otherwise permitted, and provided that you do these two things:</P>
3159 <OL TYPE="a">
3160 <LI>Accompany the combined library with a copy of the same work based on
3161  the Library, uncombined with any other library facilities. This must be
3162  distributed under the terms of the Sections above.</LI>
3163 <P></P>
3164 <LI>Give prominent notice with the combined library of the fact that
3165  part of it is a work based on the Library, and explaining where to find
3166  the accompanying uncombined form of the same work.</LI>
3167 </OL>
3168 <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with,
3169  or distribute the Library except as expressly provided under this
3170  License. Any attempt otherwise to copy, modify, sublicense, link with,
3171  or distribute the Library is void, and will automatically terminate
3172  your rights under this License. However, parties who have received
3173  copies, or rights, from you under this License will not have their
3174  licenses terminated so long as such parties remain in full compliance.</P>
3175 <P><STRONG>9.</STRONG> You are not required to accept this License,
3176  since you have not signed it. However, nothing else grants you
3177  permission to modify or distribute the Library or its derivative works.
3178  These actions are prohibited by law if you do not accept this License.
3179  Therefore, by modifying or distributing the Library (or any work based
3180  on the Library), you indicate your acceptance of this License to do so,
3181  and all its terms and conditions for copying, distributing or modifying
3182  the Library or works based on it.</P>
3183 <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
3184  work based on the Library), the recipient automatically receives a
3185  license from the original licensor to copy, distribute, link with or
3186  modify the Library subject to these terms and conditions. You may not
3187  impose any further restrictions on the recipients' exercise of the
3188  rights granted herein. You are not responsible for enforcing compliance
3189  by third parties to this License.</P>
3190 <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
3191  allegation of patent infringement or for any other reason (not limited
3192  to patent issues), conditions are imposed on you (whether by court
3193  order, agreement or otherwise) that contradict the conditions of this
3194  License, they do not excuse you from the conditions of this License. If
3195  you cannot distribute so as to satisfy simultaneously your obligations
3196  under this License and any other pertinent obligations, then as a
3197  consequence you may not distribute the Library at all. For example, if
3198  a patent license would not permit royalty-free redistribution of the
3199  Library by all those who receive copies directly or indirectly through
3200  you, then the only way you could satisfy both it and this License would
3201  be to refrain entirely from distribution of the Library.</P>
3202 <P>If any portion of this section is held invalid or unenforceable under
3203  any particular circumstance, the balance of the section is intended to
3204  apply, and the section as a whole is intended to apply in other
3205  circumstances.</P>
3206 <P>It is not the purpose of this section to induce you to infringe any
3207  patents or other property right claims or to contest validity of any
3208  such claims; this section has the sole purpose of protecting the
3209  integrity of the free software distribution system which is implemented
3210  by public license practices. Many people have made generous
3211  contributions to the wide range of software distributed through that
3212  system in reliance on consistent application of that system; it is up
3213  to the author/donor to decide if he or she is willing to distribute
3214  software through any other system and a licensee cannot impose that
3215  choice.</P>
3216 <P>This section is intended to make thoroughly clear what is believed to
3217  be a consequence of the rest of this License.</P>
3218 <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is
3219  restricted in certain countries either by patents or by copyrighted
3220  interfaces, the original copyright holder who places the Library under
3221  this License may add an explicit geographical distribution limitation
3222  excluding those countries, so that distribution is permitted only in or
3223  among countries not thus excluded. In such case, this License
3224  incorporates the limitation as if written in the body of this License.</P>
3225 <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised
3226  and/or new versions of the Library General Public License from time to
3227  time. Such new versions will be similar in spirit to the present
3228  version, but may differ in detail to address new problems or concerns.</P>
3229 <P>Each version is given a distinguishing version number. If the Library
3230  specifies a version number of this License which applies to it and &quot;any
3231  later version&quot;, you have the option of following the terms and
3232  conditions either of that version or of any later version published by
3233  the Free Software Foundation. If the Library does not specify a license
3234  version number, you may choose any version ever published by the Free
3235  Software Foundation.</P>
3236 <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
3237  into other free programs whose distribution conditions are incompatible
3238  with these, write to the author to ask for permission. For software
3239  which is copyrighted by the Free Software Foundation, write to the Free
3240  Software Foundation; we sometimes make exceptions for this. Our
3241  decision will be guided by the two goals of preserving the free status
3242  of all derivatives of our free software and of promoting the sharing
3243  and reuse of software generally.</P>
3244 <P><STRONG>NO WARRANTY</STRONG></P>
3245 <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
3246  THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
3247  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
3248  HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
3249  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
3250  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
3251  PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
3252  OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
3253  ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
3254 <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
3255  AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
3256  MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
3257  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
3258  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
3259  LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
3260  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
3261  FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
3262  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
3263  DAMAGES.</P>
3264 <H4>END OF TERMS AND CONDITIONS</H4>
3265 <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
3266 <P>This appendix lists all of the constants that are defined by the CUPS
3267  API.</P>
3268 <H2><A NAME="8_1">CUPS Constants</A></H2>
3269 <H3><A NAME="8_1_1">Version Number</A></H3>
3270 <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
3271  representing the API version number. The current version number is
3272  1.0100 which represents CUPS version 1.1.0.</P>
3273 <H3><A NAME="8_1_2">Printer Capabilities</A></H3>
3274 <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
3275  printers and classes:</P>
3276 <UL>
3277 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.</LI>
3278 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.</LI>
3279 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.</LI>
3280 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.</LI>
3281 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.</LI>
3282 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.</LI>
3283 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.</LI>
3284 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
3285  copies on its own.</LI>
3286 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.</LI>
3287 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.</LI>
3288 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.</LI>
3289 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.</LI>
3290 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.</LI>
3291 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up to
3292  9x14 inches.</LI>
3293 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media from
3294  9x14 to 18x24 inches.</LI>
3295 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media larger
3296  than 18x24 inches.</LI>
3297 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on variable
3298  or custom media sizes.</LI>
3299 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.</LI>
3300 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
3301  and option bits.</LI>
3302 </UL>
3303 <H3><A NAME="8_1_3">Encodings</A></H3>
3304 <P>CUPS defines the following character set encoding constants:</P>
3305 <UL>
3306 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.</LI>
3307 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.</LI>
3308 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.</LI>
3309 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.</LI>
3310 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.</LI>
3311 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.</LI>
3312 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.</LI>
3313 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.</LI>
3314 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.</LI>
3315 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.</LI>
3316 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.</LI>
3317 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.</LI>
3318 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.</LI>
3319 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.</LI>
3320 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.</LI>
3321 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.</LI>
3322 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.</LI>
3323 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.</LI>
3324 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.</LI>
3325 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.</LI>
3326 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.</LI>
3327 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.</LI>
3328 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.</LI>
3329 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.</LI>
3330 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.</LI>
3331 <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.</LI>
3332 <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.</LI>
3333 </UL>
3334 <H2><A NAME="8_2">HTTP Constants</A></H2>
3335 <H3><A NAME="8_2_1">Limits</A></H3>
3336 <P>The following constants define the limits for strings:</P>
3337 <UL>
3338 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.</LI>
3339 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.</LI>
3340 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.</LI>
3341 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.</LI>
3342 </UL>
3343 <H3><A NAME="8_2_2">Status Codes</A></H3>
3344 <P>The following status codes can be returned by <CODE>httpUpdate()</CODE>
3345 :</P>
3346 <UL>
3347 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred</LI>
3348 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy</LI>
3349 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was
3350  successful</LI>
3351 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful</LI>
3352 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful</LI>
3353 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't
3354  authoritative</LI>
3355 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command</LI>
3356 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated</LI>
3357 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was
3358  recieved/sent</LI>
3359 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request</LI>
3360 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently</LI>
3361 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily</LI>
3362 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...</LI>
3363 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified</LI>
3364 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI</LI>
3365 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request</LI>
3366 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host</LI>
3367 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required</LI>
3368 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI</LI>
3369 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found</LI>
3370 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed</LI>
3371 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable</LI>
3372 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is
3373  Required</LI>
3374 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out</LI>
3375 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting</LI>
3376 <LI><CODE>HTTP_GONE</CODE> - Server has gone away</LI>
3377 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is
3378  required</LI>
3379 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed</LI>
3380 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large</LI>
3381 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long</LI>
3382 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type
3383  is unsupported</LI>
3384 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error</LI>
3385 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented</LI>
3386 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway</LI>
3387 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable</LI>
3388 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out</LI>
3389 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported</LI>
3390 </UL>
3391 <H3><A NAME="8_2_3">Fields</A></H3>
3392 <P>The following fields are indices for each of the standard HTTP fields
3393  in HTTP 1/1:</P>
3394 <UL>
3395 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language</LI>
3396 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges</LI>
3397 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization</LI>
3398 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection</LI>
3399 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding</LI>
3400 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language</LI>
3401 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length</LI>
3402 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location</LI>
3403 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5</LI>
3404 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range</LI>
3405 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type</LI>
3406 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version</LI>
3407 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date</LI>
3408 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host</LI>
3409 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since</LI>
3410 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since</LI>
3411 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive</LI>
3412 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified</LI>
3413 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link</LI>
3414 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location</LI>
3415 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range</LI>
3416 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer</LI>
3417 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After</LI>
3418 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding</LI>
3419 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade</LI>
3420 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent</LI>
3421 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate</LI>
3422 </UL>
3423 <H2><A NAME="8_3">IPP Constants</A></H2>
3424 <H3><A NAME="8_3_1">Limits</A></H3>
3425 <P>The following constants define array limits for IPP data:</P>
3426 <UL>
3427 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name</LI>
3428 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values that
3429  can be read in a request.</LI>
3430 </UL>
3431 <H3><A NAME="8_3_2">Tags</A></H3>
3432 <UL>
3433 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
3434  used to separate groups of attributes</LI>
3435 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation</LI>
3436 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job</LI>
3437 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end</LI>
3438 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer</LI>
3439 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type
3440  unsupported_group</LI>
3441 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type
3442  unsupported_value</LI>
3443 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default</LI>
3444 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown</LI>
3445 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue</LI>
3446 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type
3447  notsettable</LI>
3448 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr</LI>
3449 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue</LI>
3450 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer</LI>
3451 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean</LI>
3452 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum</LI>
3453 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string</LI>
3454 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date</LI>
3455 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution</LI>
3456 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range</LI>
3457 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection</LI>
3458 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang</LI>
3459 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang</LI>
3460 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text</LI>
3461 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name</LI>
3462 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword</LI>
3463 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri</LI>
3464 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme</LI>
3465 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset</LI>
3466 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language</LI>
3467 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype</LI>
3468 </UL>
3469 <H3><A NAME="8_3_3">Resolution Units</A></H3>
3470 <P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE>
3471  constants specify dots per inch and dots per centimeter, respectively.</P>
3472 <H3><A NAME="8_3_4">Finishings</A></H3>
3473 <P>The finishing values specify special finishing operations to be
3474  performed on the job.</P>
3475 <UL>
3476 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing</LI>
3477 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job</LI>
3478 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job</LI>
3479 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job</LI>
3480 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job</LI>
3481 </UL>
3482 <H3><A NAME="8_3_5">Orientations</A></H3>
3483 <P>The orientation values specify the orientation of the job.</P>
3484 <UL>
3485 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation</LI>
3486 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise</LI>
3487 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise</LI>
3488 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees</LI>
3489 </UL>
3490 <H3><A NAME="8_3_6">Qualities</A></H3>
3491 <P>The quality values specify the desired quality of the print.</P>
3492 <UL>
3493 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality</LI>
3494 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality</LI>
3495 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality</LI>
3496 </UL>
3497 <H3><A NAME="8_3_7">Job States</A></H3>
3498 <P>The job state values are used to represent the current job state.</P>
3499 <UL>
3500 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending</LI>
3501 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held</LI>
3502 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing</LI>
3503 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped</LI>
3504 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled</LI>
3505 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted</LI>
3506 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed</LI>
3507 </UL>
3508 <H3><A NAME="8_3_8">Printer States</A></H3>
3509 <P>The printer state values are used to represent the current printer
3510  state.</P>
3511 <UL>
3512 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle</LI>
3513 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing</LI>
3514 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped</LI>
3515 </UL>
3516 <H3><A NAME="8_3_9">Operations</A></H3>
3517 <P>The operation values represent the available IPP operations.</P>
3518 <UL>
3519 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file</LI>
3520 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI</LI>
3521 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes</LI>
3522 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job</LI>
3523 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job</LI>
3524 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job</LI>
3525 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job</LI>
3526 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes</LI>
3527 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs</LI>
3528 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes</LI>
3529 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job</LI>
3530 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job</LI>
3531 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job</LI>
3532 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer</LI>
3533 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer</LI>
3534 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue</LI>
3535 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes</LI>
3536 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes</LI>
3537 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer
3538  supported values</LI>
3539 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination</LI>
3540 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers</LI>
3541 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer</LI>
3542 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer</LI>
3543 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes</LI>
3544 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class</LI>
3545 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class</LI>
3546 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class</LI>
3547 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class</LI>
3548 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination</LI>
3549 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices</LI>
3550 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs</LI>
3551 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination</LI>
3552 </UL>
3553 <H3><A NAME="8_3_10">Status Codes</A></H3>
3554 <P>Status codes are returned by all IPP requests.</P>
3555 <UL>
3556 <LI><CODE>IPP_OK</CODE> - Request completed with no errors</LI>
3557 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
3558  values were substituted</LI>
3559 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
3560  conflicted</LI>
3561 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad</LI>
3562 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource</LI>
3563 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
3564  the resource</LI>
3565 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access the
3566  resource</LI>
3567 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
3568  completed</LI>
3569 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred</LI>
3570 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found</LI>
3571 <LI><CODE>IPP_GONE</CODE> - The resource has gone away</LI>
3572 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large</LI>
3573 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value that
3574  was unknown to the server</LI>
3575 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
3576  supported by the server</LI>
3577 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing</LI>
3578 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported</LI>
3579 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported</LI>
3580 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict</LI>
3581 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
3582  compression is not supported</LI>
3583 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data contained
3584  an error</LI>
3585 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data contained
3586  an error in it</LI>
3587 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document could
3588  not be accessed</LI>
3589 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an internal
3590  error</LI>
3591 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
3592  is not supported</LI>
3593 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service is
3594  unavailable</LI>
3595 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request version is
3596  not supported</LI>
3597 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered an
3598  error</LI>
3599 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred</LI>
3600 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
3601  jobs</LI>
3602 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy</LI>
3603 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
3604  cancelled</LI>
3605 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server does not
3606  support multiple jobs</LI>
3607 </UL>
3608 <H2><A NAME="8_4">PPD Constants</A></H2>
3609 <H3><A NAME="8_4_1">PPD Format Version</A></H3>
3610 <P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
3611  representing the newest format version that is supported by CUPS,
3612  currently 4.3.</P>
3613 <H3><A NAME="8_4_2">PPD User-Interface Types</A></H3>
3614 <P>Each printer option has a type associated with it:</P>
3615 <UL>
3616 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or
3617  off</LI>
3618 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
3619  to use.</LI>
3620 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
3621  option values.</LI>
3622 </UL>
3623 <H3><A NAME="8_4_3">PPD Sections</A></H3>
3624 <P>Some options must be output before others, or in different sections
3625  of the output document. The <CODE>ppd_section_t</CODE> enumeration
3626  defines which section the option must be output in:</P>
3627 <UL>
3628 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of the
3629  document, page, or prolog sections of the document</LI>
3630 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in the
3631  DocumentSetup section of the document</LI>
3632 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before the
3633  document</LI>
3634 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the job
3635  control section of the document</LI>
3636 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
3637  PageSetup section of the document</LI>
3638 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
3639  Prolog section of the document</LI>
3640 </UL>
3641 <H3><A NAME="8_4_4">PPD Colorspaces</A></H3>
3642 <P>Each printer has a default colorspace:</P>
3643 <UL>
3644 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default</LI>
3645 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default</LI>
3646 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default</LI>
3647 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default</LI>
3648 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default</LI>
3649 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace by
3650  default</LI>
3651 </UL>
3652 <H2><A NAME="8_5">Raster Constants</A></H2>
3653 <H3><A NAME="8_5_1">Raster Sync Words</A></H3>
3654 <P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
3655  constants define the standard sync words at the beginning of each CUPS
3656  raster file.</P>
3657 <H3><A NAME="8_5_2">Raster Stream Modes</A></H3>
3658 <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
3659  constants are used with the<A HREF="#cupsRasterOpen"> <CODE>
3660 cupsRasterOpen()</CODE></A> function to specify a stream for reading or
3661  writing.</P>
3662 <H3><A NAME="8_5_3">Raster Boolean Constants</A></H3>
3663 <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
3664  represent boolean values in the page header.</P>
3665 <H3><A NAME="8_5_4">Raster Jog Values</A></H3>
3666 <P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the Jog
3667  page device dictionary variable:</P>
3668 <UL>
3669 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging</LI>
3670 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file</LI>
3671 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job</LI>
3672 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs</LI>
3673 </UL>
3674 <H3><A NAME="8_5_5">Raster Orientation Values</A></H3>
3675 <P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
3676  Orientation page device dictionary variable:</P>
3677 <UL>
3678 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation</LI>
3679 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation</LI>
3680 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation</LI>
3681 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation</LI>
3682 </UL>
3683 <H3><A NAME="8_5_6">Raster CutMedia Values</A></H3>
3684 <P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
3685  CutMedia page device dictionary variable:</P>
3686 <UL>
3687 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging</LI>
3688 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file</LI>
3689 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job</LI>
3690 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs</LI>
3691 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page</LI>
3692 </UL>
3693 <H3><A NAME="8_5_7">Raster AdvanceMedia Values</A></H3>
3694 <P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
3695  AdvanceMedia page device dictionary variable:</P>
3696 <UL>
3697 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging</LI>
3698 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file</LI>
3699 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job</LI>
3700 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs</LI>
3701 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page</LI>
3702 </UL>
3703 <H3><A NAME="8_5_8">Raster LeadingEdge Values</A></H3>
3704 <P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
3705  LeadingEdge page device dictionary variable:</P>
3706 <UL>
3707 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
3708  edge</LI>
3709 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
3710  edge</LI>
3711 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
3712  leading edge</LI>
3713 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
3714  edge</LI>
3715 </UL>
3716 <H3><A NAME="8_5_9">Raster Color Order Values</A></H3>
3717 <P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
3718  value orderings:</P>
3719 <UL>
3720 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
3721 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
3722 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
3723 </UL>
3724 <H3><A NAME="8_5_10">Raster Colorspace Values</A></H3>
3725 <P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible
3726  colorspaces:</P>
3727 <UL>
3728 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
3729 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
3730 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
3731 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
3732 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
3733 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
3734 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
3735 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
3736 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
3737 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
3738  light cyan, light magenta</LI>
3739 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
3740  magenta, metallic cyan, black</LI>
3741 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
3742  magenta, metallic cyan, metallic grey (silver)</LI>
3743 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
3744  pigment)</LI>
3745 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
3746 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
3747 </UL>
3748 <H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
3749 <P>This appendix describes all of the structures that are defined by the
3750  CUPS API.</P>
3751 <H2><A NAME="9_1">CUPS Structures</A></H2>
3752 <H3><A NAME="cups_dest_t">CUPS Destinations</A></H3>
3753 <P>The CUPS destination structure (<CODE>cups_dest_t</CODE>) contains
3754  information on a specific destination or instance:
3755 <CENTER>
3756 <TABLE BORDER="1" WIDTH="90%">
3757 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3758 <TR><TD>name</TD><TD>char *</TD><TD>The name of the printer or class.</TD>
3759 </TR>
3760 <TR><TD>instance</TD><TD>char *</TD><TD>The instance of the printer or
3761  class; NULL for the primary instance.</TD></TR>
3762 <TR><TD>is_default</TD><TD>int</TD><TD>1 if the destination is set as
3763  the default, 0 otherwise.</TD></TR>
3764 <TR><TD>num_options</TD><TD>int</TD><TD>The number of options associated
3765  with this destination.</TD></TR>
3766 <TR><TD>options</TD><TD><A HREF="#cups_option_t">cups_option_t *</A></TD><TD>
3767 The options associated with this destination.</TD></TR>
3768 </TABLE>
3769 </CENTER>
3770 </P>
3771 <H3><A NAME="cups_job_t">CUPS Jobs</A></H3>
3772 <P>The CUPS job structure (<CODE>cups_job_t</CODE>) contains information
3773  on a specific job:
3774 <CENTER>
3775 <TABLE BORDER="1" WIDTH="90%">
3776 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3777 <TR><TD>id</TD><TD>int</TD><TD>The job ID for this job.</TD></TR>
3778 <TR><TD>dest</TD><TD>char *</TD><TD>The destination for this job
3779  (printer or class name).</TD></TR>
3780 <TR><TD>title</TD><TD>char *</TD><TD>The job-name for this job (title).</TD>
3781 </TR>
3782 <TR><TD>user</TD><TD>char *</TD><TD>The job-originating-user-name for
3783  this job (username).</TD></TR>
3784 <TR><TD>format</TD><TD>char *</TD><TD>The document-format for this job
3785  (MIME type string).</TD></TR>
3786 <TR><TD>state</TD><TD>ipp_jstate</TD><TD>The current state of the job.</TD>
3787 </TR>
3788 <TR><TD>size</TD><TD>int</TD><TD>The size of this job in kilobytes.</TD></TR>
3789 <TR><TD>priority</TD><TD>int</TD><TD>The priority of this job from 1 to
3790  100 (50 is normal).</TD></TR>
3791 <TR><TD>completed_time</TD><TD>time_t</TD><TD>The time the job was
3792  completed, or 0 if not yet completed.</TD></TR>
3793 <TR><TD>creation_time</TD><TD>time_t</TD><TD>The time the job was
3794  queued.</TD></TR>
3795 <TR><TD>processing_time</TD><TD>time_t</TD><TD>The time the job started
3796  printing.</TD></TR>
3797 </TABLE>
3798 </CENTER>
3799 </P>
3800 <H3><A NAME="cups_lang_t">CUPS Messages</A></H3>
3801 <P>The CUPS messages structure (<CODE>cups_lang_t</CODE>) contains the
3802  character set, locale name, and messages array:
3803 <CENTER>
3804 <TABLE BORDER="1" WIDTH="90%">
3805 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3806 <TR><TD>next</TD><TD>cups_lang_t *</TD><TD>Pointer to the next messages
3807  structure in memory.</TD></TR>
3808 <TR><TD>used</TD><TD>int</TD><TD>The number of active users of this
3809  messages structure.</TD></TR>
3810 <TR><TD>encoding</TD><TD>cups_encoding_t</TD><TD>The character encoding
3811  of the message strings.</TD></TR>
3812 <TR><TD>language</TD><TD>char [16]</TD><TD>The language/locale name.</TD>
3813 </TR>
3814 <TR><TD>messages</TD><TD>char *[]</TD><TD>The array of message strings.</TD>
3815 </TR>
3816 </TABLE>
3817 </CENTER>
3818 </P>
3819 <H3><A NAME="cups_option_t">CUPS Options</A></H3>
3820 <P>The CUPS option structure (<CODE>cups_option_t</CODE>) contains the
3821  option name and string value:
3822 <CENTER>
3823 <TABLE BORDER="1" WIDTH="90%">
3824 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3825 <TR><TD>name</TD><TD>char *</TD><TD>The name of the option.</TD></TR>
3826 <TR><TD>value</TD><TD>char *</TD><TD>The string value of the option.</TD>
3827 </TR>
3828 </TABLE>
3829 </CENTER>
3830 </P>
3831 <H2><A NAME="9_2">Networking Structures</A></H2>
3832 <H3><A NAME="http_t">HTTP State</A></H3>
3833 <P>The HTTP state structure (<CODE>http_t</CODE>) contains the current
3834  state of a HTTP request or response:
3835 <CENTER>
3836 <TABLE BORDER="1" WIDTH="90%">
3837 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3838 <TR><TD>fd</TD><TD>int</TD><TD>The socket for the HTTP connection.</TD></TR>
3839 <TR><TD>blocking</TD><TD>int</TD><TD>1 if the HTTP functions should
3840  block, 0 if not.</TD></TR>
3841 <TR><TD>error</TD><TD>int</TD><TD>The last OS error that occurred on the
3842  socket.</TD></TR>
3843 <TR><TD>activity</TD><TD>time_t</TD><TD>The last time the HTTP
3844  connection was used.</TD></TR>
3845 <TR><TD>state</TD><TD>http_state_t</TD><TD>The current HTTP
3846  request/response state.</TD></TR>
3847 <TR><TD>status</TD><TD>int</TD><TD>The last HTTP status seen.</TD></TR>
3848 <TR><TD>version</TD><TD>http_version_t</TD><TD>The HTTP protocol version
3849  in use.</TD></TR>
3850 <TR><TD>keep_alive</TD><TD>http_keep_alive_t</TD><TD>Whether or not to
3851  use Keep-Alive</TD></TR>
3852 <TR><TD>hostaddr</TD><TD>struct sockaddr_in</TD><TD>The IPv4 address of
3853  the HTTP server.</TD></TR>
3854 <TR><TD>hostname</TD><TD>char []</TD><TD>The hostname of the HTTP
3855  server.</TD></TR>
3856 <TR><TD>fields</TD><TD>char [][]</TD><TD>The string values of all HTTP
3857  request/response fields.</TD></TR>
3858 <TR><TD>data</TD><TD>char *</TD><TD>Current byte in data buffer.</TD></TR>
3859 <TR><TD>data_encoding</TD><TD>http_encoding_t</TD><TD>The transfer
3860  encoding for the request/response.</TD></TR>
3861 <TR><TD>data_remaining</TD><TD>int</TD><TD>The number of bytes remaining
3862  in the current request, response, or chunk.</TD></TR>
3863 <TR><TD>used</TD><TD>int</TD><TD>The number of bytes that are used in
3864  the buffer.</TD></TR>
3865 <TR><TD>buffer</TD><TD>char []</TD><TD>The read/write buffer.</TD></TR>
3866 <TR><TD>auth_type</TD><TD>int</TD><TD>The type of authentication in use.</TD>
3867 </TR>
3868 <TR><TD>md5_state</TD><TD>md5_state_t</TD><TD>The current MD5 digest
3869  state.</TD></TR>
3870 <TR><TD>nonce</TD><TD>char []</TD><TD>The nonce value for Digest
3871  authentication.</TD></TR>
3872 <TR><TD>nonce_count</TD><TD>int</TD><TD>The nonce count value.</TD></TR>
3873 <TR><TD>tls</TD><TD>void *</TD><TD>A pointer to private encryption data.</TD>
3874 </TR>
3875 <TR><TD>encryption</TD><TD>http_encryption_t</TD><TD>The current
3876  encryption mode.</TD></TR>
3877 </TABLE>
3878 </CENTER>
3879 </P>
3880 <H3><A NAME="ipp_t">IPP State</A></H3>
3881 <P>The IPP state structure (<CODE>ipp_t</CODE>) contains the current
3882  state of a IPP request or response:
3883 <CENTER>
3884 <TABLE BORDER="1" WIDTH="90%">
3885 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3886 <TR><TD></TD><TD></TD><TD></TD></TR>
3887 </TABLE>
3888 </CENTER>
3889 </P>
3890 <H2><A NAME="9_3">Raster Structures</A></H2>
3891 <H3><A NAME="cups_raster_header_t">Raster Page Header</A></H3>
3892 <P>The raster page header (<CODE>cups_raster_header_t</CODE>) consists
3893  of the PostScript page device dictionary for the page:
3894 <CENTER>
3895 <TABLE BORDER="1" WIDTH="90%">
3896 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3897 <TR><TD>MediaClass</TD><TD>char[64]</TD><TD>The media class name</TD></TR>
3898 <TR><TD>MediaColor</TD><TD>char[64]</TD><TD>The media color name</TD></TR>
3899 <TR><TD>MediaType</TD><TD>char[64]</TD><TD>The media type name</TD></TR>
3900 <TR><TD>OutputType</TD><TD>char[64]</TD><TD>The output type name</TD></TR>
3901 <TR><TD>AdvanceDistance</TD><TD>unsigned</TD><TD>The distance to advance
3902  the media in points</TD></TR>
3903 <TR><TD>AdvanceMedia</TD><TD>cups_adv_t</TD><TD>When to advance the
3904  media</TD></TR>
3905 <TR><TD>Collate</TD><TD>cups_bool_t</TD><TD>Whether or not to produce
3906  collated copies</TD></TR>
3907 <TR><TD>CutMedia</TD><TD>cups_cut_t</TD><TD>When to cut the media</TD></TR>
3908 <TR><TD>Duplex</TD><TD>cups_bool_t</TD><TD>Whether or not to print on
3909  both sides of the paper</TD></TR>
3910 <TR><TD>HWResolution</TD><TD>unsigned[2]</TD><TD>The resolution of the
3911  page image in pixels per inch; the HWResolution[0] represents the
3912  horizontal resolution and HWResolution[1] represents the vertical
3913  resolution</TD></TR>
3914 <TR><TD>ImagingBoundingBox</TD><TD>unsigned[4]</TD><TD>The bounding box
3915  for the page in points; the elements represent the left, bottom, right,
3916  and top coordinates of the imaged area (if 0 then the whole page is
3917  imaged)</TD></TR>
3918 <TR><TD>InsertSheet</TD><TD>cups_bool_t</TD><TD>Whether or not to insert
3919  a sheet before this page</TD></TR>
3920 <TR><TD>Jog</TD><TD>cups_jog_t</TD><TD>When to jog copies of the page</TD>
3921 </TR>
3922 <TR><TD>LeadingEdge</TD><TD>cups_edge_t</TD><TD>The leading edge of the
3923  page</TD></TR>
3924 <TR><TD>Margins</TD><TD>unsigned[2]</TD><TD>The lower-lefthand margin of
3925  the page in points</TD></TR>
3926 <TR><TD>ManualFeed</TD><TD>cups_bool_t</TD><TD>Whether or not to
3927  manually feed the page</TD></TR>
3928 <TR><TD>MediaPosition</TD><TD>unsigned</TD><TD>The input slot number to
3929  use</TD></TR>
3930 <TR><TD>MediaWeight</TD><TD>unsigned</TD><TD>The weight of the output
3931  media in grams/m<SUP>2</SUP></TD></TR>
3932 <TR><TD>MirrorPrint</TD><TD>cups_bool_t</TD><TD>Whether or not to mirror
3933  the print</TD></TR>
3934 <TR><TD>NegativePrint</TD><TD>cups_bool_t</TD><TD>Whether or not to
3935  invert the print</TD></TR>
3936 <TR><TD>NumCopies</TD><TD>unsigned</TD><TD>The number of copies to
3937  produce</TD></TR>
3938 <TR><TD>Orientation</TD><TD>cups_orient_t</TD><TD>The orientation of the
3939  page image</TD></TR>
3940 <TR><TD>OutputFaceUp</TD><TD>cups_bool_t</TD><TD>Whether or not to
3941  output the page face up</TD></TR>
3942 <TR><TD>PageSize</TD><TD>unsigned[2]</TD><TD>The width and height of the
3943  page in points</TD></TR>
3944 <TR><TD>Separations</TD><TD>cups_bool_t</TD><TD>Whether or not to output
3945  separations</TD></TR>
3946 <TR><TD>TraySwitch</TD><TD>cups_bool_t</TD><TD>Whether or not to
3947  automatically switch trays for the requested media size/type</TD></TR>
3948 <TR><TD>Tumble</TD><TD>cups_bool_t</TD><TD>Whether or not to rotate the
3949  back side of the page</TD></TR>
3950 <TR><TD>cupsWidth</TD><TD>unsigned</TD><TD>The width of the page image
3951  in pixels</TD></TR>
3952 <TR><TD>cupsHeight</TD><TD>unsigned</TD><TD>The height of the page image
3953  in pixels</TD></TR>
3954 <TR><TD>cupsMediaType</TD><TD>unsigned</TD><TD>The device-specific media
3955  type code</TD></TR>
3956 <TR><TD>cupsBitsPerColor</TD><TD>unsigned</TD><TD>The number of bits per
3957  color</TD></TR>
3958 <TR><TD>cupsBitsPerPixel</TD><TD>unsigned</TD><TD>The number of bits per
3959  pixel</TD></TR>
3960 <TR><TD>cupsBytesPerLine</TD><TD>unsigned</TD><TD>The number of bytes
3961  per line of image data</TD></TR>
3962 <TR><TD>cupsColorOrder</TD><TD>cups_order_t</TD><TD>The order of color
3963  values</TD></TR>
3964 <TR><TD>cupsColorSpace</TD><TD>cups_cspace_t</TD><TD>The type of color
3965  values</TD></TR>
3966 <TR><TD>cupsCompression</TD><TD>unsigned</TD><TD>The device-specific
3967  compression code</TD></TR>
3968 <TR><TD>cupsRowCount</TD><TD>unsigned</TD><TD>The device-specific row
3969  count</TD></TR>
3970 <TR><TD>cupsRowFeed</TD><TD>unsigned</TD><TD>The device-specific row
3971  feed</TD></TR>
3972 <TR><TD>cupsRowStep</TD><TD>unsigned</TD><TD>The device-specific row
3973  step</TD></TR>
3974 </TABLE>
3975 </CENTER>
3976 </P>
3977 <H1 ALIGN="RIGHT"><A NAME="FUNCTIONS">D - Functions</A></H1>
3978 <P>This appendix provides a reference for all of the CUPS API functions.
3979 <!-- NEW PAGE -->
3980 </P>
3981 <H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
3982 <H3><A NAME="10_1_1">Usage</A></H3>
3983 <PRE>
3984 int
3985 cupsAddOption(const char *name,
3986               const char *value,
3987               int num_options,
3988               cups_option_t **options);
3989 </PRE>
3990 <H3><A NAME="10_1_2">Arguments</A></H3>
3991 <CENTER>
3992 <TABLE BORDER WIDTH="80%">
3993 <TR><TH>Argument</TH><TH>Description</TH></TR>
3994 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
3995 <TR><TD>value</TD><TD>The value of the option.</TD></TR>
3996 <TR><TD>num_options</TD><TD>Number of options currently in the array.</TD>
3997 </TR>
3998 <TR><TD>options</TD><TD>Pointer to the options array.</TD></TR>
3999 </TABLE>
4000 </CENTER>
4001 <H3><A NAME="10_1_3">Returns</A></H3>
4002 <P>The new number of options.</P>
4003 <H3><A NAME="10_1_4">Description</A></H3>
4004 <P><CODE>cupsAddOption()</CODE> adds an option to the specified array.</P>
4005 <H3><A NAME="10_1_5">Example</A></H3>
4006 <PRE>
4007 #include &lt;cups.h&gt;
4008
4009 ...
4010
4011 /* Declare the options array */
4012 int           num_options;
4013 <A HREF="#cups_option_t">cups_option_t</A> *options;
4014
4015 /* Initialize the options array */
4016 num_options = 0;
4017 options     = (cups_option_t *)0;
4018
4019 /* Add options using cupsAddOption() */
4020 num_options = cupsAddOption(&quot;media&quot;, &quot;letter&quot;, num_options, &amp;options);
4021 num_options = cupsAddOption(&quot;resolution&quot;, &quot;300dpi&quot;, num_options, &amp;options);
4022 </PRE>
4023 <H3><A NAME="10_1_6">See Also</A></H3>
4024 <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>,<A HREF="#cupsGetOption">
4025  <CODE>cupsGetOption()</CODE></A>,<A HREF="#cupsParseOptions"> <CODE>
4026 cupsParseOptions()</CODE></A>
4027 <!-- NEW PAGE -->
4028
4029 <H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
4030 <H3><A NAME="10_2_1">Usage</A></H3>
4031 <PRE>
4032 int
4033 cupsCancelJob(const char *dest,
4034               int job);
4035 </PRE>
4036 <H3><A NAME="10_2_2">Arguments</A></H3>
4037 <CENTER>
4038 <TABLE BORDER WIDTH="80%">
4039 <TR><TH>Argument</TH><TH>Description</TH></TR>
4040 <TR><TD>dest</TD><TD>Printer or class name</TD></TR>
4041 <TR><TD>job</TD><TD>Job ID</TD></TR>
4042 </TABLE>
4043 </CENTER>
4044 <H3><A NAME="10_2_3">Returns</A></H3>
4045 <P>1 on success, 0 on failure. On failure the error can be found by
4046  calling<A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>.</P>
4047 <H3><A NAME="10_2_4">Description</A></H3>
4048 <P><CODE>cupsCancelJob()</CODE> cancels the specifies job.</P>
4049 <H3><A NAME="10_2_5">Example</A></H3>
4050 <PRE>
4051 #include &lt;cups.h&gt;
4052
4053 cupsCancelJob(&quot;LaserJet&quot;, 1);
4054 </PRE>
4055 <H3><A NAME="10_2_6">See Also</A></H3>
4056 <P><A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>,<A HREF="#cupsPrintFile">
4057  <CODE>cupsPrintFile()</CODE></A>
4058 <!-- NEW PAGE -->
4059 </P>
4060 <H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
4061 <H3><A NAME="10_3_1">Usage</A></H3>
4062 <PRE>
4063 ipp_t *
4064 cupsDoFileRequest(http_t *http,
4065                   ipp_t *request,
4066                   const char *resource,
4067                   const char *filename);
4068 </PRE>
4069 <H3><A NAME="10_3_2">Arguments</A></H3>
4070 <CENTER>
4071 <TABLE BORDER WIDTH="80%">
4072 <TR><TH>Argument</TH><TH>Description</TH></TR>
4073 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
4074 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
4075 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
4076 <TR><TD>filename</TD><TD>File to send with POST request (<CODE>NULL</CODE>
4077  pointer if none.)</TD></TR>
4078 </TABLE>
4079 </CENTER>
4080 <H3><A NAME="10_3_3">Returns</A></H3>
4081 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
4082  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
4083 cupsLastError()</CODE></A>.</P>
4084 <H3><A NAME="10_3_4">Description</A></H3>
4085 <P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and
4086  provides the IPP request and optionally the contents of a file to the
4087  IPP server. It also handles resubmitting the request and performing
4088  password authentication as needed.</P>
4089 <H3><A NAME="10_3_5">Example</A></H3>
4090 <PRE>
4091 #include &lt;cups.h&gt;
4092
4093 <A HREF="#http_t">http_t</A>      *http;
4094 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4095 <A HREF="#ipp_t">ipp_t</A>       *request;
4096 ipp_t       *response;
4097
4098 ...
4099
4100 /* Get the default language */
4101 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
4102
4103 /* Create a new IPP request */
4104 request  = <A HREF="#ippNew">ippNew()</A>;
4105
4106 request-&gt;request.op.operation_id = IPP_PRINT_FILE;
4107 request-&gt;request.op.request_id   = 1;
4108
4109 /* Add required attributes */
4110 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
4111              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
4112
4113 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
4114              &quot;attributes-natural-language&quot;, NULL,
4115              language != NULL ? language-&gt;language : &quot;C&quot;);
4116
4117 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
4118              NULL, &quot;ipp://hostname/resource&quot;);
4119
4120 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;requesting-user-name&quot;,
4121              NULL, <A HREF="#cupsUser">cupsUser()</A>);
4122
4123 /* Do the request... */
4124 response = cupsDoFileRequest(http, request, &quot;/resource&quot;, &quot;filename.txt&quot;);
4125 </PRE>
4126 <H3><A NAME="10_3_6">See Also</A></H3>
4127 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
4128  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
4129 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
4130 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
4131  <CODE>ippNew()</CODE></A>
4132 <!-- NEW PAGE -->
4133 </P>
4134 <H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
4135 <H3><A NAME="10_4_1">Usage</A></H3>
4136 <PRE>
4137 ipp_t *
4138 cupsDoRequest(http_t *http,
4139               ipp_t *request,
4140               const char *resource);
4141 </PRE>
4142 <H3><A NAME="10_4_2">Arguments</A></H3>
4143 <CENTER>
4144 <TABLE BORDER WIDTH="80%">
4145 <TR><TH>Argument</TH><TH>Description</TH></TR>
4146 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
4147 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
4148 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
4149 </TABLE>
4150 </CENTER>
4151 <H3><A NAME="10_4_3">Returns</A></H3>
4152 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
4153  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
4154 cupsLastError()</CODE></A>.</P>
4155 <H3><A NAME="10_4_4">Description</A></H3>
4156 <P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
4157  the IPP request to the IPP server. It also handles resubmitting the
4158  request and performing password authentication as needed.</P>
4159 <H3><A NAME="10_4_5">Example</A></H3>
4160 <PRE>
4161 #include &lt;cups.h&gt;
4162
4163 <A HREF="#http_t">http_t</A>      *http;
4164 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4165 <A HREF="#ipp_t">ipp_t</A>       *request;
4166 ipp_t       *response;
4167
4168 ...
4169
4170 /* Get the default language */
4171 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
4172
4173 /* Create a new IPP request */
4174 request  = <A HREF="#ippNew">ippNew()</A>;
4175
4176 request-&gt;request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
4177 request-&gt;request.op.request_id   = 1;
4178
4179 /* Add required attributes */
4180 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
4181              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
4182
4183 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
4184              &quot;attributes-natural-language&quot;, NULL,
4185              language != NULL ? language-&gt;language : &quot;C&quot;);
4186
4187 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
4188              NULL, &quot;ipp://hostname/resource&quot;);
4189
4190 /* Do the request... */
4191 response = cupsDoRequest(http, request, &quot;/resource&quot;);
4192 </PRE>
4193 <H3><A NAME="10_4_6">See Also</A></H3>
4194 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
4195  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
4196 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
4197 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
4198  <CODE>ippNew()</CODE></A>
4199 <!-- NEW PAGE -->
4200 </P>
4201 <H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
4202 <H3><A NAME="10_5_1">Usage</A></H3>
4203 <PRE>
4204 void
4205 cupsFreeOptions(int num_options,
4206                 cups_option_t *options);
4207
4208 </PRE>
4209 <H3><A NAME="10_5_2">Arguments</A></H3>
4210 <CENTER>
4211 <TABLE BORDER WIDTH="80%">
4212 <TR><TH>Argument</TH><TH>Description</TH></TR>
4213 <TR><TD>num_options</TD><TD>Number of options in array.</TD></TR>
4214 <TR><TD>options</TD><TD>Pointer to options array.</TD></TR>
4215 </TABLE>
4216 </CENTER>
4217 <H3><A NAME="10_5_3">Description</A></H3>
4218 <P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
4219  option array specified.</P>
4220 <H3><A NAME="10_5_4">Example</A></H3>
4221 <PRE>
4222 #include &lt;cups/cups.h&gt;
4223
4224 int           num_options;
4225 cups_option_t *options;
4226
4227 ...
4228
4229 cupsFreeOptions(num_options, options);
4230 </PRE>
4231 <H3><A NAME="10_5_5">See Also</A></H3>
4232 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsGetOption">
4233  cupsGetOption()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>,<A
4234 HREF="#cupsParseOptions"> cupsParseOptions()</A>
4235 <!-- NEW PAGE -->
4236 </P>
4237 <H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
4238 <H3><A NAME="10_6_1">Usage</A></H3>
4239 <PRE>
4240 int
4241 cupsGetClasses(char ***classes);
4242 </PRE>
4243 <H3><A NAME="10_6_2">Arguments</A></H3>
4244 <CENTER>
4245 <TABLE BORDER WIDTH="80%">
4246 <TR><TH>Argument</TH><TH>Description</TH></TR>
4247 <TR><TD>classes</TD><TD>Pointer to character pointer array.</TD></TR>
4248 </TABLE>
4249 </CENTER>
4250 <H3><A NAME="10_6_3">Returns</A></H3>
4251 <P>The number of printer classes available.</P>
4252 <H3><A NAME="10_6_4">Description</A></H3>
4253 <P><CODE>cupsGetClasses()</CODE> gets a list of the available printer
4254  classes. The returned array should be freed using the <CODE>free()</CODE>
4255  when it is no longer needed.</P>
4256 <H3><A NAME="10_6_5">Example</A></H3>
4257 <PRE>
4258 #include &lt;cups/cups.h&gt;
4259
4260 int  i;
4261 int  num_classes;
4262 char **classes;
4263
4264 ...
4265
4266 num_classes = cupsGetClasses(
4267
4268 ...
4269
4270 if (num_classes &gt; 0)
4271 {
4272   for (i = 0; i &lt;num_classes; i ++)
4273     free(classes[i]);
4274
4275   free(classes);
4276 }
4277 </PRE>
4278 <H3><A NAME="10_6_6">See Also</A></H3>
4279 <P><A HREF="#cupsGetDefault"> cupsGetDefault(),<A HREF="#cupsGetPrinters">
4280  cupsGetPrinters()
4281 <!-- NEW PAGE -->
4282 </A></A></P>
4283 <H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
4284 <H3><A NAME="10_7_1">Usage</A></H3>
4285 <PRE>
4286 const char *
4287 cupsGetDefault(void);
4288 </PRE>
4289 <H3><A NAME="10_7_2">Returns</A></H3>
4290 <P>A pointer to the default destination.</P>
4291 <H3><A NAME="10_7_3">Description</A></H3>
4292 <P><CODE>cupsGetDefault()</CODE> gets the default destination printer or
4293  class. The default destination is stored in a static string and will be
4294  overwritten (usually with the same value) after each call.</P>
4295 <H3><A NAME="10_7_4">Example</A></H3>
4296 <PRE>
4297 #include &lt;cups/cups.h&gt;
4298
4299 printf(&quot;The default destination is %s\n&quot;, cupsGetDefault());
4300 </PRE>
4301 <H3><A NAME="10_7_5">See Also</A></H3>
4302 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetPrinters">
4303  cupsGetPrinters()
4304 <!-- NEW PAGE -->
4305 </A></A></P>
4306 <H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
4307 <H3><A NAME="10_8_1">Usage</A></H3>
4308 <PRE>
4309 const char *
4310 cupsGetOption(const char *name,
4311               int num_options,
4312               cups_option_t *options);
4313 </PRE>
4314 <H3><A NAME="10_8_2">Arguments</A></H3>
4315 <CENTER>
4316 <TABLE BORDER WIDTH="80%">
4317 <TR><TH>Argument</TH><TH>Description</TH></TR>
4318 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
4319 <TR><TD>num_options</TD><TD>The number of options in the array.</TD></TR>
4320 <TR><TD>options</TD><TD>The options array.</TD></TR>
4321 </TABLE>
4322 </CENTER>
4323 <H3><A NAME="10_8_3">Returns</A></H3>
4324 <P>A pointer to the option values or <CODE>NULL</CODE> if the option is
4325  not defined.</P>
4326 <H3><A NAME="10_8_4">Description</A></H3>
4327 <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
4328  named option. If the option is not included in the options array then a
4329  <CODE>NULL</CODE> pointer is returned.</P>
4330 <PRE>
4331 #include &lt;cups/cups.h&gt;
4332
4333 int           num_options;
4334 cups_option_t *options;
4335 const char    *media;
4336
4337 ...
4338
4339 media = cupsGetOption(&quot;media&quot;, num_options, options);
4340 </PRE>
4341 <H3><A NAME="10_8_5">See Also</A></H3>
4342 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4343  cupsFreeOptions()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>
4344 ,<A HREF="#cupsParseOptions"> cupsParseOptions()</A>
4345 <!-- NEW PAGE -->
4346 </P>
4347 <H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
4348 <H3><A NAME="10_9_1">Usage</A></H3>
4349 <PRE>
4350 const char *
4351 cupsGetPassword(const char *prompt);
4352 </PRE>
4353 <H3><A NAME="10_9_2">Arguments</A></H3>
4354 <CENTER>
4355 <TABLE BORDER WIDTH="80%">
4356 <TR><TH>Argument</TH><TH>Description</TH></TR>
4357 <TR><TD>prompt</TD><TD>The prompt to display to the user.</TD></TR>
4358 </TABLE>
4359 </CENTER>
4360 <H3><A NAME="10_9_3">Returns</A></H3>
4361 <P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
4362  password was entered.</P>
4363 <H3><A NAME="10_9_4">Description</A></H3>
4364 <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks
4365  the user for a password. The password text is not echoed to the user.</P>
4366 <H3><A NAME="10_9_5">Example</A></H3>
4367 <PRE>
4368 #include &lt;cups/cups.h&gt;
4369
4370 char *password;
4371
4372 ...
4373
4374 password = cupsGetPassword(&quot;Please enter a password:&quot;);
4375 </PRE>
4376 <H3><A NAME="10_9_6">See Also</A></H3>
4377 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
4378  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
4379 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser"> cupsUser()</A>
4380 <!-- NEW PAGE -->
4381
4382 </P>
4383 <H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
4384 <H3><A NAME="10_10_1">Usage</A></H3>
4385 <PRE>
4386 const char *
4387 cupsGetPPD(const char *printer);
4388 </PRE>
4389 <H3><A NAME="10_10_2">Arguments</A></H3>
4390 <CENTER>
4391 <TABLE BORDER WIDTH="80%">
4392 <TR><TH>Argument</TH><TH>Description</TH></TR>
4393 <TR><TD>printer</TD><TD>The name of the printer.</TD></TR>
4394 </TABLE>
4395 </CENTER>
4396 <H3><A NAME="10_10_3">Returns</A></H3>
4397 <P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
4398  if the printer cannot be located or does not have a PPD file.</P>
4399 <H3><A NAME="10_10_4">Description</A></H3>
4400 <P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named
4401  printer. The printer name can be of the form &quot;printer&quot; or
4402  &quot;printer@hostname&quot;.</P>
4403 <P>You should remove (unlink) the PPD file after you are done using it.
4404  The filename is stored in a static buffer and will be overwritten with
4405  each call to <CODE>cupsGetPPD()</CODE>.</P>
4406 <H3><A NAME="10_10_5">Example</A></H3>
4407 <PRE>
4408 #include &lt;cups/cups.h&gt;
4409
4410 char *ppd;
4411
4412 ...
4413
4414 ppd = cupsGetPPD(&quot;printer@hostname&quot;);
4415
4416 ...
4417
4418 unlink(ppd);
4419 </PRE>
4420
4421 <!-- NEW PAGE -->
4422 <H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
4423 <H3><A NAME="10_11_1">Usage</A></H3>
4424 <PRE>
4425 int
4426 cupsGetPrinters(char ***printers);
4427 </PRE>
4428 <H3><A NAME="10_11_2">Arguments</A></H3>
4429 <CENTER>
4430 <TABLE BORDER WIDTH="80%">
4431 <TR><TH>Argument</TH><TH>Description</TH></TR>
4432 <TR><TD>printers</TD><TD>Pointer to character pointer array.</TD></TR>
4433 </TABLE>
4434 </CENTER>
4435 <H3><A NAME="10_11_3">Returns</A></H3>
4436 <P>The number of printer printers available.</P>
4437 <H3><A NAME="10_11_4">Description</A></H3>
4438 <P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
4439  The returned array should be freed using the <CODE>free()</CODE> when
4440  it is no longer needed.</P>
4441 <H3><A NAME="10_11_5">Example</A></H3>
4442 <PRE>
4443 #include &lt;cups/cups.h&gt;
4444
4445 int  i;
4446 int  num_printers;
4447 char **printers;
4448
4449 ...
4450
4451 num_printers = cupsGetPrinters(
4452
4453 ...
4454
4455 if (num_printers &gt; 0)
4456 {
4457   for (i = 0; i &lt;num_printers; i ++)
4458     free(printers[i]);
4459
4460   free(printers);
4461 }
4462 </PRE>
4463 <H3><A NAME="10_11_6">See Also</A></H3>
4464 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetDefault">
4465  cupsGetDefault()
4466 <!-- NEW PAGE -->
4467 </A></A></P>
4468 <H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
4469 <H3><A NAME="10_12_1">Usage</A></H3>
4470 <PRE>
4471 const char *
4472 cupsLangDefault(void);
4473 </PRE>
4474 <H3><A NAME="10_12_2">Returns</A></H3>
4475 <P>A pointer to the default language structure.</P>
4476 <H3><A NAME="10_12_3">Description</A></H3>
4477 <P><CODE>cupsLangDefault()</CODE> returns a language structure for the
4478  default language. The default language is defined by the <CODE>LANG</CODE>
4479  environment variable. If the specified language cannot be located then
4480  the POSIX (English) locale is used.</P>
4481 <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with
4482  the language structure when you are done.</P>
4483 <H3><A NAME="10_12_4">Example</A></H3>
4484 <PRE>
4485 #include &lt;cups/language.h&gt;
4486
4487 cups_lang_t *language;
4488 ...
4489
4490 language = cupsLangDefault();
4491
4492 ...
4493
4494 cupsLangFree(language);
4495 </PRE>
4496 <H3><A NAME="10_12_5">See Also</A></H3>
4497 <P><A HREF="#cupsLangEncoding"> cupsLangEncoding()</A>,<A HREF="#cupsLangFlush">
4498  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4499  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4500 <!-- NEW PAGE -->
4501 </P>
4502 <H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
4503 <H3><A NAME="10_13_1">Usage</A></H3>
4504 <PRE>
4505 char *
4506 cupsLangEncoding(cups_lang_t *language);
4507 </PRE>
4508 <H3><A NAME="10_13_2">Arguments</A></H3>
4509 <CENTER>
4510 <TABLE BORDER WIDTH="80%">
4511 <TR><TH>Argument</TH><TH>Description</TH></TR>
4512 <TR><TD>language</TD><TD>The language structure.</TD></TR>
4513 </TABLE>
4514 </CENTER>
4515 <H3><A NAME="10_13_3">Returns</A></H3>
4516 <P>A pointer to the encoding string.</P>
4517 <H3><A NAME="10_13_4">Description</A></H3>
4518 <P><CODE>cupsLangEncoding()</CODE> returns the language encoding used
4519  for the specified language, e.g. &quot;iso-8859-1&quot;, &quot;utf-8&quot;, etc.</P>
4520 <H3><A NAME="10_13_5">Example</A></H3>
4521 <PRE>
4522 #include &lt;cups/language.h&gt;
4523
4524 cups_lang_t *language;
4525 char        *encoding;
4526 ...
4527
4528 language = cupsLangDefault();
4529 encoding = cupsLangEncoding(language);
4530 ...
4531
4532 cupsLangFree(language);
4533 </PRE>
4534 <H3><A NAME="10_13_6">See Also</A></H3>
4535 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangFlush">
4536  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4537  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4538 <!-- NEW PAGE -->
4539 </P>
4540 <H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
4541 <H3><A NAME="10_14_1">Usage</A></H3>
4542 <PRE>
4543 void
4544 cupsLangFlush(void);
4545 </PRE>
4546 <H3><A NAME="10_14_2">Description</A></H3>
4547 <P><CODE>cupsLangFlush()</CODE> frees all language structures that have
4548  been allocated.</P>
4549 <H3><A NAME="10_14_3">Example</A></H3>
4550 <PRE>
4551 #include &lt;cups/language.h&gt;
4552
4553 ...
4554
4555 cupsLangFlush();
4556 </PRE>
4557 <H3><A NAME="10_14_4">See Also</A></H3>
4558 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4559  cupsLangEncoding()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4560  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4561 <!-- NEW PAGE -->
4562 </P>
4563 <H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
4564 <H3><A NAME="10_15_1">Usage</A></H3>
4565 <PRE>
4566 void
4567 cupsLangFree(cups_lang_t *language);
4568 </PRE>
4569 <H3><A NAME="10_15_2">Arguments</A></H3>
4570 <CENTER>
4571 <TABLE BORDER WIDTH="80%">
4572 <TR><TH>Argument</TH><TH>Description</TH></TR>
4573 <TR><TD>language</TD><TD>The language structure to free.</TD></TR>
4574 </TABLE>
4575 </CENTER>
4576 <H3><A NAME="10_15_3">Description</A></H3>
4577 <P><CODE>cupsLangFree()</CODE> frees the specified language structure.</P>
4578 <H3><A NAME="10_15_4">Example</A></H3>
4579 <PRE>
4580 #include &lt;cups/language.h&gt;
4581
4582 cups_lang_t *language;
4583 ...
4584
4585 cupsLangFree(language);
4586 </PRE>
4587 <H3><A NAME="10_15_5">See Also</A></H3>
4588 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4589  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangGet">
4590  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4591 <!-- NEW PAGE -->
4592 </P>
4593 <H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
4594 <H3><A NAME="10_16_1">Usage</A></H3>
4595 <PRE>
4596 cups_lang_t *
4597 cupsLangGet(const char *name);
4598 </PRE>
4599 <H3><A NAME="10_16_2">Arguments</A></H3>
4600 <CENTER>
4601 <TABLE BORDER WIDTH="80%">
4602 <TR><TH>Argument</TH><TH>Description</TH></TR>
4603 <TR><TD>name</TD><TD>The name of the locale.</TD></TR>
4604 </TABLE>
4605 </CENTER>
4606 <H3><A NAME="10_16_3">Returns</A></H3>
4607 <P>A pointer to a language structure.</P>
4608 <H3><A NAME="10_16_4">Description</A></H3>
4609 <P><CODE>cupsLangGet()</CODE> returns a language structure for the
4610  specified locale. If the locale is not defined then the POSIX (English)
4611  locale is substituted.</P>
4612 <H3><A NAME="10_16_5">Example</A></H3>
4613 <PRE>
4614 #include &lt;cups/language.h&gt;
4615
4616 cups_lang_t *language;
4617
4618 ...
4619
4620 language = cupsLangGet(&quot;fr&quot;);
4621
4622 ...
4623
4624 cupsLangFree(language);
4625 </PRE>
4626 <H3><A NAME="10_16_6">See Also</A></H3>
4627 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4628  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4629  cupsLangFree()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4630 <!-- NEW PAGE -->
4631 </P>
4632 <H2><A NAME="cupsLangString">cupsLangString()</A></H2>
4633 <H3><A NAME="10_17_1">Usage</A></H3>
4634 <PRE>
4635 char *
4636 cupsLangString(cups_lang_t *language,
4637                int         message);
4638 </PRE>
4639 <H3><A NAME="10_17_2">Arguments</A></H3>
4640 <CENTER>
4641 <TABLE BORDER WIDTH="80%">
4642 <TR><TH>Argument</TH><TH>Description</TH></TR>
4643 <TR><TD>language</TD><TD>The language to query.</TD></TR>
4644 <TR><TD>message</TD><TD>The message number.</TD></TR>
4645 </TABLE>
4646 </CENTER>
4647 <H3><A NAME="10_17_3">Returns</A></H3>
4648 <P>A pointer to the message string or <CODE>NULL</CODE> if the message
4649  is not defined.</P>
4650 <H3><A NAME="10_17_4">Description</A></H3>
4651 <P><CODE>cupsLangString()</CODE> returns a pointer to the specified
4652  message string in the specified language.</P>
4653 <H3><A NAME="10_17_5">Example</A></H3>
4654 <PRE>
4655 #include &lt;cups/language.h&gt;
4656
4657 cups_lang_t *language;
4658 char        *s;
4659 ...
4660
4661 language = cupsLangGet(&quot;fr&quot;);
4662
4663 s = cupsLangString(language, CUPS_MSG_YES);
4664
4665 ...
4666
4667 cupsLangFree(language);
4668 </PRE>
4669 <H3><A NAME="10_17_6">See Also</A></H3>
4670 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4671  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4672  cupsLangFree()</A>,<A HREF="#cupsLangGet"> cupsLangGet()</A>
4673 <!-- NEW PAGE -->
4674 </P>
4675 <H2><A NAME="cupsLastError">cupsLastError()</A></H2>
4676 <H3><A NAME="10_18_1">Usage</A></H3>
4677 <PRE>
4678 ipp_status_t
4679 cupsLastError(void);
4680 </PRE>
4681 <H3><A NAME="10_18_2">Returns</A></H3>
4682 <P>An enumeration containing the last IPP error.</P>
4683 <H3><A NAME="10_18_3">Description</A></H3>
4684 <P><CODE>cupsLastError()</CODE> returns the last IPP error that
4685  occurred. If no error occurred then it will return <CODE>IPP_OK</CODE>
4686  or <CODE>IPP_OK_CONFLICT</CODE>.</P>
4687 <H3><A NAME="10_18_4">Example</A></H3>
4688 <PRE>
4689 #include &lt;cups/cups.h&gt;
4690
4691 ipp_status_t status;
4692
4693 ...
4694
4695 status = cupsLastError();
4696 </PRE>
4697 <H3><A NAME="10_18_5">See Also</A></H3>
4698 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsPrintFile">
4699  cupsPrintFile()</A>
4700 <!-- NEW PAGE -->
4701 </P>
4702 <H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
4703 <H3><A NAME="10_19_1">Usage</A></H3>
4704 <PRE>
4705 int
4706 cupsMarkOptions(ppd_file_t *ppd,
4707                 int num_options,
4708                 cups_option_t *options);
4709 </PRE>
4710 <H3><A NAME="10_19_2">Arguments</A></H3>
4711 <CENTER>
4712 <TABLE BORDER WIDTH="80%">
4713 <TR><TH>Argument</TH><TH>Description</TH></TR>
4714 <TR><TD>ppd</TD><TD>The PPD file to mark.</TD></TR>
4715 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4716 </TR>
4717 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4718 </TABLE>
4719 </CENTER>
4720 <H3><A NAME="10_19_3">Returns</A></H3>
4721 <P>The number of conflicts found.</P>
4722 <H3><A NAME="10_19_4">Description</A></H3>
4723 <P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
4724  handles mapping of IPP option names and values to PPD option names.</P>
4725 <H3><A NAME="10_19_5">Example</A></H3>
4726 <PRE>
4727 #include &lt;cups/cups.h&gt;
4728
4729 int           num_options;
4730 cups_option_t *options;
4731 ppd_file_t    *ppd;
4732
4733 ...
4734
4735 cupsMarkOptions(ppd, num_options, options);
4736 </PRE>
4737 <H3><A NAME="10_19_6">See Also</A></H3>
4738 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4739  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsParseOptions">
4740  cupsParseOptions()</A>
4741 <!-- NEW PAGE -->
4742 </P>
4743 <H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
4744 <H3><A NAME="10_20_1">Usage</A></H3>
4745 <PRE>
4746 int
4747 cupsParseOptions(const char *arg,
4748                  int num_options,
4749                  cups_option_t **options);
4750 </PRE>
4751 <H3><A NAME="10_20_2">Arguments</A></H3>
4752 <CENTER>
4753 <TABLE BORDER WIDTH="80%">
4754 <TR><TH>Argument</TH><TH>Description</TH></TR>
4755 <TR><TD>arg</TD><TD>The string containing one or more options.</TD></TR>
4756 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4757 </TR>
4758 <TR><TD>options</TD><TD>A pointer to the options array pointer.</TD></TR>
4759 </TABLE>
4760 </CENTER>
4761 <H3><A NAME="10_20_3">Returns</A></H3>
4762 <P>The new number of options in the array.</P>
4763 <H3><A NAME="10_20_4">Description</A></H3>
4764 <P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
4765  or more options of the form &quot;name=value&quot;, &quot;name&quot;, or &quot;noname&quot;. It can
4766  be called multiple times to combine the options from several strings.</P>
4767 <H3><A NAME="10_20_5">Example</A></H3>
4768 <PRE>
4769 #include &lt;cups/cups.h&gt;
4770
4771 int           num_options;
4772 cups_option_t *options;
4773
4774 ...
4775
4776 num_options = 0;
4777 options     = (cups_option_t *)0;
4778 num_options = cupsParseOptions(argv[5], num_options, &amp;options);
4779 </PRE>
4780 <H3><A NAME="10_20_6">See Also</A></H3>
4781 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4782  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsMarkOptions">
4783  cupsMarkOptions()</A>
4784 <!-- NEW PAGE -->
4785 </P>
4786 <H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
4787 <H3><A NAME="10_21_1">Usage</A></H3>
4788 <PRE>
4789 int
4790 cupsPrintFile(const char    *printer,
4791               const char    *filename,
4792               const char    *title,
4793               int           num_options,
4794               cups_option_t *options);
4795 </PRE>
4796 <H3><A NAME="10_21_2">Arguments</A></H3>
4797 <CENTER>
4798 <TABLE BORDER WIDTH="80%">
4799 <TR><TH>Argument</TH><TH>Description</TH></TR>
4800 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4801 <TR><TD>filename</TD><TD>The file to print.</TD></TR>
4802 <TR><TD>title</TD><TD>The job title.</TD></TR>
4803 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4804 </TR>
4805 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4806 </TABLE>
4807 </CENTER>
4808 <H3><A NAME="10_21_3">Returns</A></H3>
4809 <P>The new job ID number or 0 on error.</P>
4810 <H3><A NAME="10_21_4">Description</A></H3>
4811 <P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
4812  class for printing. If the job cannot be printed the error code can be
4813  found by calling <CODE>cupsLastError()</CODE>.</P>
4814 <H3><A NAME="10_21_5">Example</A></H3>
4815 <PRE>
4816 #include &lt;cups/cups.h&gt;
4817
4818 int           num_options;
4819 cups_option_t *options;
4820 int           jobid;
4821
4822 ...
4823
4824 jobid = cupsPrintFile(&quot;printer@hostname&quot;, &quot;filename.ps&quot;, &quot;Job Title&quot;,
4825                       num_options, options);
4826 </PRE>
4827 <H3><A NAME="10_21_6">See Also</A></H3>
4828 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4829  cupsLastError()</A>,<A HREF="#cupsPrintFiles"> cupsPrintFiles()</A>
4830 <!-- NEW PAGE -->
4831 </P>
4832 <H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
4833 <H3><A NAME="10_22_1">Usage</A></H3>
4834 <PRE>
4835 int
4836 cupsPrintFiles(const char    *printer,
4837                int           num_files,
4838                const char    **files,
4839                const char    *title,
4840                int           num_options,
4841                cups_option_t *options);
4842 </PRE>
4843 <H3><A NAME="10_22_2">Arguments</A></H3>
4844 <CENTER>
4845 <TABLE BORDER WIDTH="80%">
4846 <TR><TH>Argument</TH><TH>Description</TH></TR>
4847 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4848 <TR><TD>num_files</TD><TD>The number of files to print.</TD></TR>
4849 <TR><TD>files</TD><TD>The files to print.</TD></TR>
4850 <TR><TD>title</TD><TD>The job title.</TD></TR>
4851 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4852 </TR>
4853 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4854 </TABLE>
4855 </CENTER>
4856 <H3><A NAME="10_22_3">Returns</A></H3>
4857 <P>The new job ID number or 0 on error.</P>
4858 <H3><A NAME="10_22_4">Description</A></H3>
4859 <P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4860  printer or class for printing. If the job cannot be printed the error
4861  code can be found by calling <CODE>cupsLastError()</CODE>.</P>
4862 <H3><A NAME="10_22_5">Example</A></H3>
4863 <PRE>
4864 #include &lt;cups/cups.h&gt;
4865
4866 int           num_files;
4867 const char    *files[100];
4868 int           num_options;
4869 cups_option_t *options;
4870 int           jobid;
4871
4872 ...
4873
4874 jobid = cupsPrintFiles(&quot;printer@hostname&quot;, num_files, files,
4875                        &quot;Job Title&quot;, num_options, options);
4876 </PRE>
4877 <H3><A NAME="10_22_6">See Also</A></H3>
4878 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4879  cupsLastError()</A>,<A HREF="#cupsPrintFile"> cupsPrintFile()</A>
4880 <!-- NEW PAGE -->
4881 </P>
4882 <H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
4883 <H3><A NAME="10_23_1">Usage</A></H3>
4884 <PRE>
4885 void
4886 cupsRasterClose(cups_raster_t *ras);
4887 </PRE>
4888 <H3><A NAME="10_23_2">Arguments</A></H3>
4889 <CENTER>
4890 <TABLE BORDER WIDTH="80%">
4891 <TR><TH>Argument</TH><TH>Description</TH></TR>
4892 <TR><TD>ras</TD><TD>The raster stream to close.</TD></TR>
4893 </TABLE>
4894 </CENTER>
4895 <H3><A NAME="10_23_3">Description</A></H3>
4896 <P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.</P>
4897 <H3><A NAME="10_23_4">Example</A></H3>
4898 <PRE>
4899 #include &lt;cups/raster.h&gt;
4900
4901 cups_raster_t *ras;
4902
4903 ...
4904
4905 cupsRasterClose(ras);
4906 </PRE>
4907 <H3><A NAME="10_23_5">See Also</A></H3>
4908 <P><A HREF="#cupsRasterOpen"> cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4909  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4910  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4911  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4912  cupsRasterWritePixels()</A>
4913 <!-- NEW PAGE -->
4914 </P>
4915 <H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
4916 <H3><A NAME="10_24_1">Usage</A></H3>
4917 <PRE>
4918 cups_raster_t *
4919 cupsRasterOpen(int fd,
4920                cups_mode_t mode);
4921 </PRE>
4922 <H3><A NAME="10_24_2">Arguments</A></H3>
4923 <CENTER>
4924 <TABLE BORDER WIDTH="80%">
4925 <TR><TH>Argument</TH><TH>Description</TH></TR>
4926 <TR><TD>fd</TD><TD>The file descriptor to use.</TD></TR>
4927 <TR><TD>mode</TD><TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or <CODE>
4928 CUPS_RASTER_WRITE</CODE>.</TD></TR>
4929 </TABLE>
4930 </CENTER>
4931 <H3><A NAME="10_24_3">Returns</A></H3>
4932 <P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an
4933  error.</P>
4934 <H3><A NAME="10_24_4">Description</A></H3>
4935 <P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or
4936  writing.</P>
4937 <H3><A NAME="10_24_5">Example</A></H3>
4938 <PRE>
4939 #include &lt;cups/raster.h&gt;
4940
4941 cups_raster_t *ras;
4942
4943 ...
4944
4945 ras = cupsRasterOpen(0, CUPS_RASTER_READ);
4946 </PRE>
4947 <H3><A NAME="10_24_6">See Also</A></H3>
4948 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterReadHeader">
4949  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4950  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4951  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4952  cupsRasterWritePixels()</A>
4953 <!-- NEW PAGE -->
4954 </P>
4955 <H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
4956 <H3><A NAME="10_25_1">Usage</A></H3>
4957 <PRE>
4958 unsigned
4959 cupsRasterReadHeader(cups_raster_t *ras,
4960                      cups_page_header_t *header);
4961 </PRE>
4962 <H3><A NAME="10_25_2">Arguments</A></H3>
4963 <CENTER>
4964 <TABLE BORDER WIDTH="80%">
4965 <TR><TH>Argument</TH><TH>Description</TH></TR>
4966 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
4967 <TR><TD>header</TD><TD>A pointer to a page header structure to read
4968  into.</TD></TR>
4969 </TABLE>
4970 </CENTER>
4971 <H3><A NAME="10_25_3">Returns</A></H3>
4972 <P>1 on success, 0 on EOF or error.</P>
4973 <H3><A NAME="10_25_4">Description</A></H3>
4974 <P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the
4975  specified raster stream.</P>
4976 <H3><A NAME="10_25_5">Example</A></H3>
4977 <PRE>
4978 #include &lt;cups/raster.h&gt;
4979
4980 int                  line;
4981 cups_raster_t        *ras;
4982 cups_raster_header_t header;
4983 unsigned char        pixels[8192];
4984 ...
4985
4986 while (cupsRasterReadHeader(ras, &amp;header))
4987 {
4988   ...
4989
4990   for (line = 0; line &lt; header.cupsHeight; line ++)
4991   {
4992     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4993
4994     ...
4995   }
4996 }
4997 </PRE>
4998 <H3><A NAME="10_25_6">See Also</A></H3>
4999 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
5000  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadPixels">
5001  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
5002  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
5003  cupsRasterWritePixels()</A>
5004 <!-- NEW PAGE -->
5005 </P>
5006 <H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
5007 <H3><A NAME="10_26_1">Usage</A></H3>
5008 <PRE>
5009 unsigned
5010 cupsRasterReadPixels(cups_raster_t *ras,
5011                      unsigned char *pixels,
5012                      unsigned length);
5013 </PRE>
5014 <H3><A NAME="10_26_2">Arguments</A></H3>
5015 <CENTER>
5016 <TABLE BORDER WIDTH="80%">
5017 <TR><TH>Argument</TH><TH>Description</TH></TR>
5018 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
5019 <TR><TD>pixels</TD><TD>The pointer to a pixel buffer.</TD></TR>
5020 <TR><TD>length</TD><TD>The number of bytes of pixel data to read.</TD></TR>
5021 </TABLE>
5022 </CENTER>
5023 <H3><A NAME="10_26_3">Returns</A></H3>
5024 <P>The number of bytes read or 0 on EOF or error.</P>
5025 <H3><A NAME="10_26_4">Description</A></H3>
5026 <P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the
5027  specified raster stream.</P>
5028 <H3><A NAME="10_26_5">Example</A></H3>
5029 <PRE>
5030 #include &lt;cups/raster.h&gt;
5031
5032 int                  line;
5033 cups_raster_t        *ras;
5034 cups_raster_header_t header;
5035 unsigned char        pixels[8192];
5036 ...
5037
5038 while (cupsRasterReadHeader(ras, &amp;header))
5039 {
5040   ...
5041
5042   for (line = 0; line &lt; header.cupsHeight; line ++)
5043   {
5044     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
5045
5046     ...
5047   }
5048 }
5049 </PRE>
5050 <H3><A NAME="10_26_6">See Also</A></H3>
5051 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
5052  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
5053  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterWriteHeader">
5054  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
5055  cupsRasterWritePixels()</A>
5056 <!-- NEW PAGE -->
5057 </P>
5058 <H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
5059 <H3><A NAME="10_27_1">Usage</A></H3>
5060 <PRE>
5061 unsigned
5062 cupsRasterWriteHeader(cups_raster_t *ras,
5063                       cups_page_header_t *header);
5064 </PRE>
5065 <H3><A NAME="10_27_2">Arguments</A></H3>
5066 <CENTER>
5067 <TABLE BORDER WIDTH="80%">
5068 <TR><TH>Argument</TH><TH>Description</TH></TR>
5069 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
5070 <TR><TD>header</TD><TD>A pointer to the page header to write.</TD></TR>
5071 </TABLE>
5072 </CENTER>
5073 <H3><A NAME="10_27_3">Returns</A></H3>
5074 <P>1 on success, 0 on error.</P>
5075 <H3><A NAME="10_27_4">Description</A></H3>
5076 <P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header
5077  to a raster stream.</P>
5078 <H3><A NAME="10_27_5">Example</A></H3>
5079 <PRE>
5080 #include &lt;cups/raster.h&gt;
5081
5082 int                  line;
5083 cups_raster_t        *ras;
5084 cups_raster_header_t header;
5085 unsigned char        pixels[8192];
5086 ...
5087
5088 cupsRasterWriteHeader(ras, &amp;header);
5089
5090 for (line = 0; line &lt; header.cupsHeight; line ++)
5091 {
5092   ...
5093
5094   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5095 }
5096 </PRE>
5097 <H3><A NAME="10_27_6">See Also</A></H3>
5098 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
5099  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
5100  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
5101  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWritePixels">
5102  cupsRasterWritePixels()</A>
5103 <!-- NEW PAGE -->
5104 </P>
5105 <H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
5106 <H3><A NAME="10_28_1">Usage</A></H3>
5107 <PRE>
5108 unsigned
5109 cupsRasterWritePixels(cups_raster_t *ras,
5110                       unsigned char *pixels,
5111                       unsigned length);
5112 </PRE>
5113 <H3><A NAME="10_28_2">Arguments</A></H3>
5114 <CENTER>
5115 <TABLE BORDER WIDTH="80%">
5116 <TR><TH>Argument</TH><TH>Description</TH></TR>
5117 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
5118 <TR><TD>pixels</TD><TD>The pixel data to write.</TD></TR>
5119 <TR><TD>length</TD><TD>The number of bytes to write.</TD></TR>
5120 </TABLE>
5121 </CENTER>
5122 <H3><A NAME="10_28_3">Returns</A></H3>
5123 <P>The number of bytes written.</P>
5124 <H3><A NAME="10_28_4">Description</A></H3>
5125 <P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data
5126  to a raster stream.</P>
5127 <H3><A NAME="10_28_5">Example</A></H3>
5128 <PRE>
5129 #include &lt;cups/raster.h&gt;
5130
5131 int                  line;
5132 cups_raster_t        *ras;
5133 cups_raster_header_t header;
5134 unsigned char        pixels[8192];
5135 ...
5136
5137 cupsRasterWriteHeader(ras, &amp;header);
5138
5139 for (line = 0; line &lt; header.cupsHeight; line ++)
5140 {
5141   ...
5142
5143   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5144 }
5145 </PRE>
5146 <H3><A NAME="10_28_6">See Also</A></H3>
5147 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
5148  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
5149  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
5150  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
5151  cupsRasterWriteHeader()</A>
5152 <!-- NEW PAGE -->
5153 </P>
5154 <H2><A NAME="cupsServer">cupsServer()</A></H2>
5155 <H3><A NAME="10_29_1">Usage</A></H3>
5156 <PRE>
5157 const char *
5158 cupsServer(void);
5159 </PRE>
5160 <H3><A NAME="10_29_2">Returns</A></H3>
5161 <P>A pointer to the default server name.</P>
5162 <H3><A NAME="10_29_3">Description</A></H3>
5163 <P><CODE>cupsServer()</CODE> returns a pointer to the default server
5164  name. The server name is stored in a static location and will be
5165  overwritten with every call to <CODE>cupsServer()</CODE></P>
5166 <P>The default server is determined from the following locations:</P>
5167 <OL>
5168 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,</LI>
5169 <LI>The <CODE>ServerName</CODE> directive in the<VAR> client.conf</VAR>
5170  file,</LI>
5171 <LI>The default host, &quot;localhost&quot;.</LI>
5172 </OL>
5173 <H3><A NAME="10_29_4">Example</A></H3>
5174 <PRE>
5175 #include &lt;cups/cups.h&gt;
5176
5177 const char *server;
5178
5179 server = cupsServer();
5180 </PRE>
5181 <H3><A NAME="10_29_5">See Also</A></H3>
5182 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsSetPasswordCB">
5183  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
5184 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser"> cupsUser()</A>
5185 <!-- NEW PAGE -->
5186
5187 </P>
5188 <H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
5189 <H3><A NAME="10_30_1">Usage</A></H3>
5190 <PRE>
5191 void
5192 cupsSetPasswordCB(const char *(*cb)(const char *prompt));
5193 </PRE>
5194 <H3><A NAME="10_30_2">Arguments</A></H3>
5195 <CENTER>
5196 <TABLE BORDER WIDTH="80%">
5197 <TR><TH>Argument</TH><TH>Description</TH></TR>
5198 <TR><TD>cb</TD><TD>The password callback function.</TD></TR>
5199 </TABLE>
5200 </CENTER>
5201 <H3><A NAME="10_30_3">Description</A></H3>
5202 <P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use
5203  when asking the user for a password. The callback function must accept
5204  a single character string pointer (the prompt string) and return <CODE>
5205 NULL</CODE> if the user did not enter a password string or a pointer to
5206  the password string otherwise.</P>
5207 <H3><A NAME="10_30_4">Example</A></H3>
5208 <PRE>
5209 #include &lt;cups/cups.h&gt;
5210
5211 const char *
5212 my_password_cb(const char *prompt)
5213 {
5214   return (getpass(prompt));
5215 }
5216
5217 ...
5218
5219 char *password;
5220
5221 ...
5222
5223 cupsSetPasswordCB(my_password_cb);
5224 password = cupsGetPassword(&quot;Please enter a password:&quot;);
5225 </PRE>
5226 <H3><A NAME="10_30_5">See Also</A></H3>
5227 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetServer">
5228  cupsSetServer()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser">
5229  cupsUser()</A>
5230 <!-- NEW PAGE -->
5231 </P>
5232 <H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
5233 <H3><A NAME="10_31_1">Usage</A></H3>
5234 <PRE>
5235 void
5236 cupsSetServer(const char *server);
5237 </PRE>
5238 <H3><A NAME="10_31_2">Arguments</A></H3>
5239 <CENTER>
5240 <TABLE BORDER WIDTH="80%">
5241 <TR><TH>Argument</TH><TH>Description</TH></TR>
5242 <TR><TD>server</TD><TD>The default server to use.</TD></TR>
5243 </TABLE>
5244 </CENTER>
5245 <H3><A NAME="10_31_3">Description</A></H3>
5246 <P><CODE>cupsSetServer()</CODE> sets the default server to use for the
5247  CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>, the
5248  default server is used.</P>
5249 <H3><A NAME="10_31_4">Example</A></H3>
5250 <PRE>
5251 #include &lt;cups/cups.h&gt;
5252
5253 cupsSetServer(&quot;foo.bar.com&quot;);
5254 </PRE>
5255 <H3><A NAME="10_31_5">See Also</A></H3>
5256 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5257  cupsSetPasswordCB()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser">
5258  cupsUser()</A>
5259 <!-- NEW PAGE -->
5260 </P>
5261 <H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
5262 <H3><A NAME="10_32_1">Usage</A></H3>
5263 <PRE>
5264 void
5265 cupsSetUser(const char *user);
5266 </PRE>
5267 <H3><A NAME="10_32_2">Arguments</A></H3>
5268 <CENTER>
5269 <TABLE BORDER WIDTH="80%">
5270 <TR><TH>Argument</TH><TH>Description</TH></TR>
5271 <TR><TD>user</TD><TD>The user name string to use.</TD></TR>
5272 </TABLE>
5273 </CENTER>
5274 <H3><A NAME="10_32_3">Description</A></H3>
5275 <P><CODE>cupsSetUser()</CODE> sets the default user name for
5276  authentication. If the <CODE>user</CODE> argument is <CODE>NULL</CODE>
5277  then the current login user is used.</P>
5278 <H3><A NAME="10_32_4">Example</A></H3>
5279 <PRE>
5280 #include &lt;cups/cups.h&gt;
5281
5282 ...
5283
5284 cupsSetUser(&quot;root&quot;);
5285 </PRE>
5286 <H3><A NAME="10_32_5">See Also</A></H3>
5287 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5288  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
5289 HREF="#cupsUser"> cupsUser()</A>
5290 <!-- NEW PAGE -->
5291 </P>
5292 <H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
5293 <H3><A NAME="10_33_1">Usage</A></H3>
5294 <PRE>
5295 char *
5296 cupsTempFile(char *filename,
5297              int length);
5298 </PRE>
5299 <H3><A NAME="10_33_2">Arguments</A></H3>
5300 <CENTER>
5301 <TABLE BORDER WIDTH="80%">
5302 <TR><TH>Argument</TH><TH>Description</TH></TR>
5303 <TR><TD>filename</TD><TD>The character string to hold the temporary
5304  filename.</TD></TR>
5305 <TR><TD>length</TD><TD>The size of the filename string in bytes.</TD></TR>
5306 </TABLE>
5307 </CENTER>
5308 <H3><A NAME="10_33_3">Returns</A></H3>
5309 <P>A pointer to <CODE>filename</CODE>.</P>
5310 <H3><A NAME="10_33_4">Description</A></H3>
5311 <P><CODE>cupsTempFile()</CODE> generates a temporary filename for the<VAR>
5312  /var/tmp</VAR> directory or the directory specified by the <CODE>TMPDIR</CODE>
5313  environment variable.</P>
5314 <H3><A NAME="10_33_5">Example</A></H3>
5315 <PRE>
5316 #include &lt;cups/cups.h&gt;
5317
5318 char filename[256];
5319
5320 cupsTempFile(filename, sizeof(filename));
5321 </PRE>
5322
5323 <!-- NEW PAGE -->
5324 <H2><A NAME="cupsUser">cupsUser()</A></H2>
5325 <H3><A NAME="10_34_1">Usage</A></H3>
5326 <PRE>
5327 const char *
5328 cupsUser(void);
5329 </PRE>
5330 <H3><A NAME="10_34_2">Returns</A></H3>
5331 <P>A pointer to the current username or <CODE>NULL</CODE> if the user ID
5332  is undefined.</P>
5333 <H3><A NAME="10_34_3">Description</A></H3>
5334 <P><CODE>cupsUser()</CODE> returns the name associated with the current
5335  user ID as reported by the <CODE>getuid()</CODE> system call.</P>
5336 <H3><A NAME="10_34_4">Example</A></H3>
5337 <PRE>
5338 #include &lt;cups/cups.h&gt;
5339
5340 const char *user;
5341
5342 user = cupsUser();
5343 </PRE>
5344 <H3><A NAME="10_34_5">See Also</A></H3>
5345 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsServer">
5346  cupsServer()</A>
5347 <!-- NEW PAGE -->
5348 </P>
5349 <H2><A NAME="httpBlocking">httpBlocking()</A></H2>
5350 <H3><A NAME="10_35_1">Usage</A></H3>
5351 <PRE>
5352 void httpBlocking(http_t *http, int blocking)
5353 </PRE>
5354 <H3><A NAME="10_35_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>blocking</TD><TD>0 if the connection should be non-blocking, 1
5360  if it should be blocking</TD></TR>
5361 </TABLE>
5362 </CENTER>
5363 <H3><A NAME="10_35_3">Description</A></H3>
5364 <P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for
5365  the HTTP connection. By default HTTP connections will block (stop) the
5366  client program until data is available or can be sent to the server.</P>
5367 <H3><A NAME="10_35_4">Example</A></H3>
5368 <PRE>
5369 #include &lt;cups/http.h&gt;
5370
5371 http_t *http;
5372
5373 http = httpConnect(&quot;server&quot;, port);
5374 httpBlocking(http, 0);
5375 </PRE>
5376 <H3><A NAME="10_35_5">See Also</A></H3>
5377 <A HREF="#httpCheck"> <CODE>httpCheck()</CODE></A>,<A HREF="#httpConnect">
5378  <CODE>httpConnect()</CODE></A>
5379 <!-- NEW PAGE -->
5380
5381 <H2><A NAME="httpCheck">httpCheck()</A></H2>
5382 <H3><A NAME="10_36_1">Usage</A></H3>
5383 <PRE>
5384 int httpCheck(http_t *http);
5385 </PRE>
5386 <H3><A NAME="10_36_2">Arguments</A></H3>
5387 <CENTER>
5388 <TABLE BORDER WIDTH="80%">
5389 <TR><TH>Argument</TH><TH>Description</TH></TR>
5390 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5391 </TABLE>
5392 </CENTER>
5393 <H3><A NAME="10_36_3">Returns</A></H3>
5394 <P>0 if there is no data pending, 1 otherwise.</P>
5395 <H3><A NAME="10_36_4">Description</A></H3>
5396 <P>The <CODE>httpCheck()</CODE> function checks to see if there is any
5397  data pending on an HTTP connection.</P>
5398 <H3><A NAME="10_36_5">Example</A></H3>
5399 <PRE>
5400 #include &lt;cups/http.h&gt;
5401
5402 http_t *http;
5403
5404 if (httpCheck(http))
5405 {
5406   ... do something ...
5407 }
5408 </PRE>
5409 <H3><A NAME="10_36_6">See Also</A></H3>
5410 <A HREF="#httpBlocking"> <CODE>httpBlocking()</CODE></A>,<A HREF="#httpConnect">
5411  <CODE>httpConnect()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE>
5412 </A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE></A>
5413 <!-- NEW PAGE -->
5414
5415 <H2><A NAME="httpClearFields">httpClearFields()</A></H2>
5416 <H3><A NAME="10_37_1">Usage</A></H3>
5417 <PRE>
5418 void httpClearFields(http_t *http)
5419 </PRE>
5420 <H3><A NAME="10_37_2">Arguments</A></H3>
5421 <CENTER>
5422 <TABLE BORDER WIDTH="80%">
5423 <TR><TH>Argument</TH><TH>Description</TH></TR>
5424 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5425 </TABLE>
5426 </CENTER>
5427 <H3><A NAME="10_37_3">Description</A></H3>
5428 <P>The <CODE>httpClearFields()</CODE> function clears all HTTP request
5429  fields for the HTTP connection.</P>
5430 <H3><A NAME="10_37_4">Example</A></H3>
5431 <PRE>
5432 #include &lt;cups/http.h&gt;
5433
5434 http_t *http;
5435
5436 httpClearFields(http);
5437 </PRE>
5438 <H3><A NAME="10_37_5">See Also</A></H3>
5439 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
5440  <CODE>httpGetField()</CODE></A>,<A HREF="#httpSetField"> <CODE>
5441 httpSetField()</CODE></A>
5442 <!-- NEW PAGE -->
5443
5444 <H2><A NAME="httpClose">httpClose()</A></H2>
5445 <H3><A NAME="10_38_1">Usage</A></H3>
5446 <PRE>
5447 void httpClose(http_t *http);
5448 </PRE>
5449 <H3><A NAME="10_38_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_38_3">Description</A></H3>
5457 <P>The <CODE>httpClose()</CODE> function closes an active HTTP
5458  connection.</P>
5459 <H3><A NAME="10_38_4">Example</A></H3>
5460 <PRE>
5461 #include &lt;cups/http.h&gt;
5462
5463 http_t *http;
5464
5465 httpClose(http);
5466 </PRE>
5467 <H3><A NAME="10_38_5">See Also</A></H3>
5468 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5469 <!-- NEW PAGE -->
5470
5471 <H2><A NAME="httpConnect">httpConnect()</A></H2>
5472 <H3><A NAME="10_39_1">Usage</A></H3>
5473 <PRE>
5474 http_t *httpConnect(const char *hostname, int port);
5475 </PRE>
5476 <H3><A NAME="10_39_2">Arguments</A></H3>
5477 <CENTER>
5478 <TABLE BORDER WIDTH="80%">
5479 <TR><TH>Argument</TH><TH>Description</TH></TR>
5480 <TR><TD>hostname</TD><TD>The name or IP address of the server to connect
5481  to</TD></TR>
5482 <TR><TD>port</TD><TD>The port number to use</TD></TR>
5483 </TABLE>
5484 </CENTER>
5485 <H3><A NAME="10_39_3">Returns</A></H3>
5486 <P>A pointer to a HTTP connection structure or NULL if the connection
5487  could not be made.</P>
5488 <H3><A NAME="10_39_4">Description</A></H3>
5489 <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to
5490  the specified server and port.</P>
5491 <H3><A NAME="10_39_5">Example</A></H3>
5492 <PRE>
5493 #include &lt;cups/http.h&gt;
5494
5495 http_t *http;
5496
5497 http = httpConnect(cupsServer(), ippPort());
5498 </PRE>
5499 <H3><A NAME="10_39_6">See Also</A></H3>
5500 <A HREF="#httpClose"> <CODE>httpClose()</CODE></A>,<A HREF="#httpGet"> <CODE>
5501 httpGet()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE></A>,<A HREF="#httpPost">
5502  <CODE>httpPost()</CODE></A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE>
5503 </A>,<A HREF="#httpWrite"> <CODE>httpWrite()</CODE></A>
5504 <!-- NEW PAGE -->
5505
5506 <H2><A NAME="httpDecode64">httpDecode64()</A></H2>
5507 <H3><A NAME="10_40_1">Usage</A></H3>
5508 <PRE>
5509 char *httpDecode64(char *out, const char *in);
5510 </PRE>
5511 <H3><A NAME="10_40_2">Arguments</A></H3>
5512 <CENTER>
5513 <TABLE BORDER WIDTH="80%">
5514 <TR><TH>Argument</TH><TH>Description</TH></TR>
5515 <TR><TD>out</TD><TD>The output string</TD></TR>
5516 <TR><TD>in</TD><TD>The input string</TD></TR>
5517 </TABLE>
5518 </CENTER>
5519 <H3><A NAME="10_40_3">Returns</A></H3>
5520 <P>A pointer to the decoded string.</P>
5521 <H3><A NAME="10_40_4">Description</A></H3>
5522 <P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded
5523  string to the original string.</P>
5524 <H3><A NAME="10_40_5">Example</A></H3>
5525 <PRE>
5526 #include &lt;cups/http.h&gt;
5527
5528 char encoded_string[255];
5529 char original_string[255];
5530
5531 httpDecode64(original_string, encoded_string);
5532 </PRE>
5533 <H3><A NAME="10_40_6">See Also</A></H3>
5534 <A HREF="#httpEncode64"> <CODE>httpEncode64()</CODE></A>
5535 <!-- NEW PAGE -->
5536
5537 <H2><A NAME="httpDelete">httpDelete()</A></H2>
5538 <H3><A NAME="10_41_1">Usage</A></H3>
5539 <PRE>
5540 int httpDelete(http_t *http, const char *uri);
5541 </PRE>
5542 <H3><A NAME="10_41_2">Arguments</A></H3>
5543 <CENTER>
5544 <TABLE BORDER WIDTH="80%">
5545 <TR><TH>Argument</TH><TH>Description</TH></TR>
5546 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5547 <TR><TD>uri</TD><TD>The URI to delete</TD></TR>
5548 </TABLE>
5549 </CENTER>
5550 <H3><A NAME="10_41_3">Returns</A></H3>
5551 <P>0 on success, non-zero on failure.</P>
5552 <H3><A NAME="10_41_4">Description</A></H3>
5553 <P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
5554  the server.</P>
5555 <H3><A NAME="10_41_5">Example</A></H3>
5556 <PRE>
5557 #include &lt;cups/http.h&gt;
5558
5559 http_t *http;
5560
5561 httpDelete(http, &quot;/some/uri&quot;);
5562 </PRE>
5563 <H3><A NAME="10_41_6">See Also</A></H3>
5564 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5565  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5566 httpUpdate()</CODE></A>
5567 <!-- NEW PAGE -->
5568
5569 <H2><A NAME="httpEncode64">httpEncode64()</A></H2>
5570 <H3><A NAME="10_42_1">Usage</A></H3>
5571 <PRE>
5572 char *httpEncode64(char *out, const char *in);
5573 </PRE>
5574 <H3><A NAME="10_42_2">Arguments</A></H3>
5575 <CENTER>
5576 <TABLE BORDER WIDTH="80%">
5577 <TR><TH>Argument</TH><TH>Description</TH></TR>
5578 <TR><TD>out</TD><TD>The output string</TD></TR>
5579 <TR><TD>in</TD><TD>The input string</TD></TR>
5580 </TABLE>
5581 </CENTER>
5582 <H3><A NAME="10_42_3">Returns</A></H3>
5583 <P>A pointer to the encoded string.</P>
5584 <H3><A NAME="10_42_4">Description</A></H3>
5585 <P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded
5586  string to the original string.</P>
5587 <H3><A NAME="10_42_5">Example</A></H3>
5588 <PRE>
5589 #include &lt;cups/http.h&gt;
5590
5591 char encoded_string[255];
5592 char original_string[255];
5593
5594 httpEncode64(encoded_string, original_string);
5595 </PRE>
5596 <H3><A NAME="10_42_6">See Also</A></H3>
5597 <A HREF="#httpDecode64"> <CODE>httpDecode64()</CODE></A>
5598 <!-- NEW PAGE -->
5599
5600 <H2><A NAME="httpError">httpError()</A></H2>
5601 <H3><A NAME="10_43_1">Usage</A></H3>
5602 <PRE>
5603 int httpError(http_t *http);
5604 </PRE>
5605 <H3><A NAME="10_43_2">Arguments</A></H3>
5606 <CENTER>
5607 <TABLE BORDER WIDTH="80%">
5608 <TR><TH>Argument</TH><TH>Description</TH></TR>
5609 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5610 </TABLE>
5611 </CENTER>
5612 <H3><A NAME="10_43_3">Returns</A></H3>
5613 <P>The last error that occurred or 0 if no error has occurred.</P>
5614 <H3><A NAME="10_43_4">Description</A></H3>
5615 <P>The <CODE>httpError()</CODE> function returns the last error that
5616  occurred on the HTTP connection.</P>
5617 <H3><A NAME="10_43_5">Example</A></H3>
5618 <PRE>
5619 #include &lt;cups/http.h&gt;
5620
5621 http_t *http;
5622
5623 if (httpError(http))
5624 {
5625   ... show an error message ...
5626 }
5627 </PRE>
5628 <H3><A NAME="10_43_6">See Also</A></H3>
5629 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5630 <!-- NEW PAGE -->
5631
5632 <H2><A NAME="httpFlush">httpFlush()</A></H2>
5633 <H3><A NAME="10_44_1">Usage</A></H3>
5634 <PRE>
5635 void httpFlush(http_t *http);
5636 </PRE>
5637 <H3><A NAME="10_44_2">Arguments</A></H3>
5638 <CENTER>
5639 <TABLE BORDER WIDTH="80%">
5640 <TR><TH>Argument</TH><TH>Description</TH></TR>
5641 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5642 </TABLE>
5643 </CENTER>
5644 <H3><A NAME="10_44_3">Description</A></H3>
5645 <P>The <CODE>httpFlush()</CODE> function flushes any remaining data left
5646  from a GET or POST operation.</P>
5647 <H3><A NAME="10_44_4">Example</A></H3>
5648 <PRE>
5649 #include &lt;cups/http.h&gt;
5650
5651 http_t *http;
5652
5653 httpFlush(http);
5654 </PRE>
5655 <H3><A NAME="10_44_5">See Also</A></H3>
5656 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,
5657 <!-- NEW PAGE -->
5658
5659 <H2><A NAME="httpGet">httpGet()</A></H2>
5660 <H3><A NAME="10_45_1">Usage</A></H3>
5661 <PRE>
5662 int httpGet(http_t *http, const char *uri);
5663 </PRE>
5664 <H3><A NAME="10_45_2">Arguments</A></H3>
5665 <CENTER>
5666 <TABLE BORDER WIDTH="80%">
5667 <TR><TH>Argument</TH><TH>Description</TH></TR>
5668 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5669 <TR><TD>uri</TD><TD>The URI to get</TD></TR>
5670 </TABLE>
5671 </CENTER>
5672 <H3><A NAME="10_45_3">Returns</A></H3>
5673 <P>0 on success, non-zero on failure.</P>
5674 <H3><A NAME="10_45_4">Description</A></H3>
5675 <P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
5676  server.</P>
5677 <H3><A NAME="10_45_5">Example</A></H3>
5678 <PRE>
5679 #include &lt;cups/http.h&gt;
5680
5681 http_t *http;
5682
5683 httpGet(http, &quot;/some/uri&quot;);
5684 </PRE>
5685 <H3><A NAME="10_45_6">See Also</A></H3>
5686 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5687  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5688 httpUpdate()</CODE></A>
5689 <!-- NEW PAGE -->
5690
5691 <H2><A NAME="httpGets">httpGets()</A></H2>
5692 <H3><A NAME="10_46_1">Usage</A></H3>
5693 <PRE>
5694 char *httpGets(char *line, int length, http_t *http)
5695 </PRE>
5696 <H3><A NAME="10_46_2">Arguments</A></H3>
5697 <CENTER>
5698 <TABLE BORDER WIDTH="80%">
5699 <TR><TH>Argument</TH><TH>Description</TH></TR>
5700 <TR><TD>line</TD><TD>The string to fill with a line from the HTTP
5701  connection</TD></TR>
5702 <TR><TD>length</TD><TD>The maximum length of the string</TD></TR>
5703 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5704 </TABLE>
5705 </CENTER>
5706 <H3><A NAME="10_46_3">Returns</A></H3>
5707 <P>A pointer to the string or NULL if no line could be retrieved.</P>
5708 <H3><A NAME="10_46_4">Description</A></H3>
5709 <P>The <CODE>httpGets()</CODE> function is used to read a request line
5710  from the HTTP connection. It is not normally used by a client program.</P>
5711 <H3><A NAME="10_46_5">Example</A></H3>
5712 <PRE>
5713 #include &lt;cups/http.h&gt;
5714
5715 http_t *http;
5716 char line[1024];
5717
5718 if (httpGets(line, sizeof(line), http))
5719 {
5720   ... process the line ...
5721 }
5722 </PRE>
5723 <H3><A NAME="10_46_6">See Also</A></H3>
5724 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpUpdate">
5725  <CODE>httpUpdate()</CODE></A>
5726 <!-- NEW PAGE -->
5727
5728 <H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
5729 <H3><A NAME="10_47_1">Usage</A></H3>
5730 <PRE>
5731 const char *httpGetDateString(time_t time)
5732 </PRE>
5733 <H3><A NAME="10_47_2">Arguments</A></H3>
5734 <CENTER>
5735 <TABLE BORDER WIDTH="80%">
5736 <TR><TH>Argument</TH><TH>Description</TH></TR>
5737 <TR><TD>time</TD><TD>The UNIX date/time value</TD></TR>
5738 </TABLE>
5739 </CENTER>
5740 <H3><A NAME="10_47_3">Returns</A></H3>
5741 <P>A pointer to a static string containing the HTTP date/time string for
5742  the specified UNIX time value.</P>
5743 <H3><A NAME="10_47_4">Description</A></H3>
5744 <P>The <CODE>httpGetDateString()</CODE> function generates a date/time
5745  string suitable for HTTP requests from a UNIX time value.</P>
5746 <H3><A NAME="10_47_5">Example</A></H3>
5747 <PRE>
5748 #include &lt;cups/http.h&gt;
5749
5750 puts(httpGetDateString(time(NULL)));
5751 </PRE>
5752 <H3><A NAME="10_47_6">See Also</A></H3>
5753 <A HREF="#httpGetDateTime"> <CODE>httpGetDateTime()</CODE></A>
5754 <!-- NEW PAGE -->
5755
5756 <H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
5757 <H3><A NAME="10_48_1">Usage</A></H3>
5758 <PRE>
5759 time_t httpGetDateTime(const char *date)
5760 </PRE>
5761 <H3><A NAME="10_48_2">Arguments</A></H3>
5762 <CENTER>
5763 <TABLE BORDER WIDTH="80%">
5764 <TR><TH>Argument</TH><TH>Description</TH></TR>
5765 <TR><TD>date</TD><TD>The HTTP date/time string</TD></TR>
5766 </TABLE>
5767 </CENTER>
5768 <H3><A NAME="10_48_3">Returns</A></H3>
5769 <P>A UNIX time value.</P>
5770 <H3><A NAME="10_48_4">Description</A></H3>
5771 <P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP date/time
5772  string to a UNIX time value.</P>
5773 <H3><A NAME="10_48_5">Example</A></H3>
5774 <PRE>
5775 #include &lt;cups/http.h&gt;
5776
5777 printf(&quot;%d\n&quot;, httpGetDateTime(&quot;Fri, 30 June 2000 12:34:56 GMT&quot;));
5778 </PRE>
5779 <H3><A NAME="10_48_6">See Also</A></H3>
5780 <A HREF="#httpGetDateString"> <CODE>httpGetDateString()</CODE></A>
5781 <!-- NEW PAGE -->
5782
5783 <H2><A NAME="httpGetField">httpGetField()</A></H2>
5784 <H3><A NAME="10_49_1">Usage</A></H3>
5785 <PRE>
5786 const char *httpGetField(http_t *http, http_field_t field);
5787 </PRE>
5788 <H3><A NAME="10_49_2">Arguments</A></H3>
5789 <CENTER>
5790 <TABLE BORDER WIDTH="80%">
5791 <TR><TH>Argument</TH><TH>Description</TH></TR>
5792 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5793 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
5794 </TABLE>
5795 </CENTER>
5796 <H3><A NAME="10_49_3">Returns</A></H3>
5797 <P>A pointer to the field value string.</P>
5798 <H3><A NAME="10_49_4">Description</A></H3>
5799 <P>The <CODE>httpGetField()</CODE> function returns the current value
5800  for the specified HTTP field.</P>
5801 <H3><A NAME="10_49_5">Example</A></H3>
5802 <PRE>
5803 #include &lt;cups/http.h&gt;
5804
5805 http_t *http;
5806
5807 httpGet(http, &quot;/some/uri&quot;);
5808 while (httpUpdate(http) == HTTP_CONTINUE);
5809
5810 puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
5811 </PRE>
5812 <H3><A NAME="10_49_6">See Also</A></H3>
5813 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5814  <CODE>httpSetField()</CODE></A>
5815 <!-- NEW PAGE -->
5816
5817 <H2><A NAME="httpHead">httpHead()</A></H2>
5818 <H3><A NAME="10_50_1">Usage</A></H3>
5819 <PRE>
5820 int httpHead(http_t *http, const char *uri);
5821 </PRE>
5822 <H3><A NAME="10_50_2">Arguments</A></H3>
5823 <CENTER>
5824 <TABLE BORDER WIDTH="80%">
5825 <TR><TH>Argument</TH><TH>Description</TH></TR>
5826 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5827 <TR><TD>uri</TD><TD>The URI to head</TD></TR>
5828 </TABLE>
5829 </CENTER>
5830 <H3><A NAME="10_50_3">Returns</A></H3>
5831 <P>0 on success, non-zero on failure.</P>
5832 <H3><A NAME="10_50_4">Description</A></H3>
5833 <P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
5834  server.</P>
5835 <H3><A NAME="10_50_5">Example</A></H3>
5836 <PRE>
5837 #include &lt;cups/http.h&gt;
5838
5839 http_t *http;
5840
5841 httpHead(http, &quot;/some/uri&quot;);
5842 </PRE>
5843 <H3><A NAME="10_50_6">See Also</A></H3>
5844 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5845  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5846 httpUpdate()</CODE></A>
5847 <!-- NEW PAGE -->
5848
5849 <H2><A NAME="httpInitialize">httpInitialize()</A></H2>
5850 <H3><A NAME="10_51_1">Usage</A></H3>
5851 <PRE>
5852 void httpInitialize(void);
5853 </PRE>
5854 <H3><A NAME="10_51_2">Description</A></H3>
5855 <P>The <CODE>httpInitialize()</CODE> function initializes the networking
5856  code as needed by the underlying platform. It is called automatically
5857  by the <CODE>httpConnect()</CODE> function.</P>
5858 <H3><A NAME="10_51_3">Example</A></H3>
5859 <PRE>
5860 #include &lt;cups/http.h&gt;
5861
5862 httpInitialize();
5863 </PRE>
5864 <H3><A NAME="10_51_4">See Also</A></H3>
5865 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5866 <!-- NEW PAGE -->
5867
5868 <H2><A NAME="httpOptions">httpOptions()</A></H2>
5869 <H3><A NAME="10_52_1">Usage</A></H3>
5870 <PRE>
5871 int httpOptions(http_t *http, const char *uri);
5872 </PRE>
5873 <H3><A NAME="10_52_2">Arguments</A></H3>
5874 <CENTER>
5875 <TABLE BORDER WIDTH="80%">
5876 <TR><TH>Argument</TH><TH>Description</TH></TR>
5877 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5878 <TR><TD>uri</TD><TD>The URI to check for options</TD></TR>
5879 </TABLE>
5880 </CENTER>
5881 <H3><A NAME="10_52_3">Returns</A></H3>
5882 <P>0 on success, non-zero on failure.</P>
5883 <H3><A NAME="10_52_4">Description</A></H3>
5884 <P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request
5885  to the server.</P>
5886 <H3><A NAME="10_52_5">Example</A></H3>
5887 <PRE>
5888 #include &lt;cups/http.h&gt;
5889
5890 http_t *http;
5891
5892 httpOptions(http, &quot;/some/uri&quot;);
5893 </PRE>
5894 <H3><A NAME="10_52_6">See Also</A></H3>
5895 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5896  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5897 httpUpdate()</CODE></A>
5898 <!-- NEW PAGE -->
5899
5900 <H2><A NAME="httpPost">httpPost()</A></H2>
5901 <H3><A NAME="10_53_1">Usage</A></H3>
5902 <PRE>
5903 int httpPost(http_t *http, const char *uri);
5904 </PRE>
5905 <H3><A NAME="10_53_2">Arguments</A></H3>
5906 <CENTER>
5907 <TABLE BORDER WIDTH="80%">
5908 <TR><TH>Argument</TH><TH>Description</TH></TR>
5909 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5910 <TR><TD>uri</TD><TD>The URI to post to</TD></TR>
5911 </TABLE>
5912 </CENTER>
5913 <H3><A NAME="10_53_3">Returns</A></H3>
5914 <P>0 on success, non-zero on failure.</P>
5915 <H3><A NAME="10_53_4">Description</A></H3>
5916 <P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
5917  server.</P>
5918 <H3><A NAME="10_53_5">Example</A></H3>
5919 <PRE>
5920 #include &lt;cups/http.h&gt;
5921
5922 http_t *http;
5923
5924 httpPost(http, &quot;/some/uri&quot;);
5925 </PRE>
5926 <H3><A NAME="10_53_6">See Also</A></H3>
5927 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5928  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5929 httpUpdate()</CODE></A>
5930 <!-- NEW PAGE -->
5931
5932 <H2><A NAME="httpPrintf">httpPrintf()</A></H2>
5933 <H3><A NAME="10_54_1">Usage</A></H3>
5934 <PRE>
5935 int httpPrintf(http_t *http, const char *format, ...);
5936 </PRE>
5937 <H3><A NAME="10_54_2">Arguments</A></H3>
5938 <CENTER>
5939 <TABLE BORDER WIDTH="80%">
5940 <TR><TH>Argument</TH><TH>Description</TH></TR>
5941 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5942 <TR><TD>format</TD><TD>A printf-style format string</TD></TR>
5943 </TABLE>
5944 </CENTER>
5945 <H3><A NAME="10_54_3">Returns</A></H3>
5946 <P>The number of bytes written.</P>
5947 <H3><A NAME="10_54_4">Description</A></H3>
5948 <P>The <CODE>httpPrintf()</CODE> function sends a formatted string to
5949  the HTTP connection. It is normally only used by the CUPS API and
5950  scheduler.</P>
5951 <H3><A NAME="10_54_5">Example</A></H3>
5952 <PRE>
5953 #include &lt;cups/http.h&gt;
5954
5955 http_t *http;
5956
5957 httpPrintf(http, &quot;GET / HTTP/1.1 \r\n&quot;);
5958 </PRE>
5959 <H3><A NAME="10_54_6">See Also</A></H3>
5960 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5961 <!-- NEW PAGE -->
5962
5963 <H2><A NAME="httpPut">httpPut()</A></H2>
5964 <H3><A NAME="10_55_1">Usage</A></H3>
5965 <PRE>
5966 int httpPut(http_t *http, const char *uri);
5967 </PRE>
5968 <H3><A NAME="10_55_2">Arguments</A></H3>
5969 <CENTER>
5970 <TABLE BORDER WIDTH="80%">
5971 <TR><TH>Argument</TH><TH>Description</TH></TR>
5972 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5973 <TR><TD>uri</TD><TD>The URI to put</TD></TR>
5974 </TABLE>
5975 </CENTER>
5976 <H3><A NAME="10_55_3">Returns</A></H3>
5977 <P>0 on success, non-zero on failure.</P>
5978 <H3><A NAME="10_55_4">Description</A></H3>
5979 <P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
5980  server.</P>
5981 <H3><A NAME="10_55_5">Example</A></H3>
5982 <PRE>
5983 #include &lt;cups/http.h&gt;
5984
5985 http_t *http;
5986
5987 httpDelete(http, &quot;/some/uri&quot;);
5988 </PRE>
5989 <H3><A NAME="10_55_6">See Also</A></H3>
5990 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5991  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5992 httpUpdate()</CODE></A>
5993 <!-- NEW PAGE -->
5994
5995 <H2><A NAME="httpRead">httpRead()</A></H2>
5996 <H3><A NAME="10_56_1">Usage</A></H3>
5997 <PRE>
5998 int httpRead(http_t *http, char *buffer, int length);
5999 </PRE>
6000 <H3><A NAME="10_56_2">Arguments</A></H3>
6001 <CENTER>
6002 <TABLE BORDER WIDTH="80%">
6003 <TR><TH>Argument</TH><TH>Description</TH></TR>
6004 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6005 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
6006 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
6007 </TABLE>
6008 </CENTER>
6009 <H3><A NAME="10_56_3">Returns</A></H3>
6010 <P>The number of bytes read or -1 on error.</P>
6011 <H3><A NAME="10_56_4">Description</A></H3>
6012 <P>The <CODE>httpRead()</CODE> function reads data from the HTTP
6013  connection, possibly the result of a GET or POST request.</P>
6014 <H3><A NAME="10_56_5">Example</A></H3>
6015 <PRE>
6016 #include &lt;cups/http.h&gt;
6017
6018 http_t *http;
6019 char buffer[1024];
6020 int  bytes;
6021
6022 httpGet(http, &quot;/&quot;);
6023 while (httpUpdate(http) != HTTP_CONTINUE);
6024 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
6025 {
6026   buffer[bytes] = '\0';
6027   fputs(buffer, stdout);
6028 }
6029 </PRE>
6030 <H3><A NAME="10_56_6">See Also</A></H3>
6031 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpWrite">
6032  <CODE>httpWrite()</CODE></A>
6033 <!-- NEW PAGE -->
6034
6035 <H2><A NAME="httpReconnect">httpReconnect()</A></H2>
6036 <H3><A NAME="10_57_1">Usage</A></H3>
6037 <PRE>
6038 int httpReconnect(http_t *http);
6039 </PRE>
6040 <H3><A NAME="10_57_2">Arguments</A></H3>
6041 <CENTER>
6042 <TABLE BORDER WIDTH="80%">
6043 <TR><TH>Argument</TH><TH>Description</TH></TR>
6044 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6045 </TABLE>
6046 </CENTER>
6047 <H3><A NAME="10_57_3">Returns</A></H3>
6048 <P>0 on success, non-zero on failure.</P>
6049 <H3><A NAME="10_57_4">Description</A></H3>
6050 <P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP
6051  server. This is usually done automatically if the HTTP functions detect
6052  that the server connection has terminated.</P>
6053 <H3><A NAME="10_57_5">Example</A></H3>
6054 <PRE>
6055 #include &lt;cups/http.h&gt;
6056
6057 http_t *http;
6058
6059 httpReconnect(http);
6060 </PRE>
6061 <H3><A NAME="10_57_6">See Also</A></H3>
6062 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
6063 <!-- NEW PAGE -->
6064
6065 <H2><A NAME="httpSeparate">httpSeparate()</A></H2>
6066 <H3><A NAME="10_58_1">Usage</A></H3>
6067 <PRE>
6068 void httpSeparate(const char *uri, char *method,
6069                   char *username, char *host, int *port,
6070                   char *resource);
6071 </PRE>
6072 <H3><A NAME="10_58_2">Arguments</A></H3>
6073 <CENTER>
6074 <TABLE BORDER WIDTH="80%">
6075 <TR><TH>Argument</TH><TH>Description</TH></TR>
6076 <TR><TD>uri</TD><TD>The URI to separate</TD></TR>
6077 <TR><TD>method</TD><TD>The method (scheme) of the URI</TD></TR>
6078 <TR><TD>username</TD><TD>The username (and password) portion of the URI,
6079  if any</TD></TR>
6080 <TR><TD>host</TD><TD>The hostname portion of the URI, if any</TD></TR>
6081 <TR><TD>port</TD><TD>The port number for the URI, either as specified or
6082  as default for the method/scheme</TD></TR>
6083 <TR><TD>resource</TD><TD>The resource string, usually a filename on the
6084  server</TD></TR>
6085 </TABLE>
6086 </CENTER>
6087 <H3><A NAME="10_58_3">Description</A></H3>
6088 <P>The <CODE>httpSeparate()</CODE> function separates the specified URI
6089  into its component parts. The method, username, hostname, and resource
6090  strings should be at least <CODE>HTTP_MAX_URI</CODE> characters long to
6091  avoid potential buffer overflow problems.</P>
6092 <H3><A NAME="10_58_4">Example</A></H3>
6093 <PRE>
6094 char uri[HTTP_MAX_URI];
6095 char method[HTTP_MAX_URI];
6096 char username[HTTP_MAX_URI];
6097 char host[HTTP_MAX_URI];
6098 char resource[HTTP_MAX_URI];
6099 int port;
6100
6101 httpSeparate(uri, method, username, host, &amp;port, resource);
6102 </PRE>
6103 <H3><A NAME="10_58_5">See Also</A></H3>
6104 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
6105 <!-- NEW PAGE -->
6106
6107 <H2><A NAME="httpSetField">httpSetField()</A></H2>
6108 <H3><A NAME="10_59_1">Usage</A></H3>
6109 <PRE>
6110 void httpSetField(http_t *http, http_field_t field, const char *value);
6111 </PRE>
6112 <H3><A NAME="10_59_2">Arguments</A></H3>
6113 <CENTER>
6114 <TABLE BORDER WIDTH="80%">
6115 <TR><TH>Argument</TH><TH>Description</TH></TR>
6116 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6117 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
6118 <TR><TD>value</TD><TD>The string value for the field</TD></TR>
6119 </TABLE>
6120 </CENTER>
6121 <H3><A NAME="10_59_3">Description</A></H3>
6122 <P>The <CODE>httpSetField()</CODE> function sets the current value for
6123  the specified HTTP field.</P>
6124 <H3><A NAME="10_59_4">Example</A></H3>
6125 <PRE>
6126 #include &lt;cups/http.h&gt;
6127
6128 http_t *http;
6129
6130 httpSetField(http, HTTP_FIELD_AUTHORIZATION, &quot;Basic dfdr34453454325&quot;));
6131 httpGet(http, &quot;/some/uri&quot;);
6132 while (httpUpdate(http) == HTTP_CONTINUE);
6133 </PRE>
6134 <H3><A NAME="10_59_5">See Also</A></H3>
6135 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
6136  <CODE>httpGetField()</CODE></A>
6137 <!-- NEW PAGE -->
6138
6139 <H2><A NAME="httpTrace">httpTrace()</A></H2>
6140 <H3><A NAME="10_60_1">Usage</A></H3>
6141 <PRE>
6142 int httpTrace(http_t *http, const char *uri);
6143 </PRE>
6144 <H3><A NAME="10_60_2">Arguments</A></H3>
6145 <CENTER>
6146 <TABLE BORDER WIDTH="80%">
6147 <TR><TH>Argument</TH><TH>Description</TH></TR>
6148 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6149 <TR><TD>uri</TD><TD>The URI to trace</TD></TR>
6150 </TABLE>
6151 </CENTER>
6152 <H3><A NAME="10_60_3">Returns</A></H3>
6153 <P>0 on success, non-zero on failure.</P>
6154 <H3><A NAME="10_60_4">Description</A></H3>
6155 <P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to
6156  the server.</P>
6157 <H3><A NAME="10_60_5">Example</A></H3>
6158 <PRE>
6159 #include &lt;cups/http.h&gt;
6160
6161 http_t *http;
6162
6163 httpTrace(http, &quot;/some/uri&quot;);
6164 </PRE>
6165 <H3><A NAME="10_60_6">See Also</A></H3>
6166 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
6167  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
6168 httpUpdate()</CODE></A>
6169 <!-- NEW PAGE -->
6170
6171 <H2><A NAME="httpUpdate">httpUpdate()</A></H2>
6172 <H3><A NAME="10_61_1">Usage</A></H3>
6173 <PRE>
6174 http_status_t httpUpdate(http_t *http);
6175 </PRE>
6176 <H3><A NAME="10_61_2">Arguments</A></H3>
6177 <CENTER>
6178 <TABLE BORDER WIDTH="80%">
6179 <TR><TH>Argument</TH><TH>Description</TH></TR>
6180 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6181 </TABLE>
6182 </CENTER>
6183 <H3><A NAME="10_61_3">Returns</A></H3>
6184 <P>The HTTP status of the current request.</P>
6185 <H3><A NAME="10_61_4">Description</A></H3>
6186 <P>The <CODE>httpUpdate()</CODE> function updates the current request
6187  status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or
6188  TRACE request to finalize the HTTP request and retrieve the request
6189  status.</P>
6190 <P>Since proxies and the current blocking mode can cause the request to
6191  take longer, programs should continue calling <CODE>httpUpdate()</CODE>
6192  until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>
6193 .</P>
6194 <H3><A NAME="10_61_5">Example</A></H3>
6195 <PRE>
6196 #include &lt;cups/http.h&gt;
6197
6198 http_t *http;
6199 http_status_t status;
6200
6201 httpGet(http, &quot;/some/uri&quot;);
6202 while ((status = httpUpdate(http)) == HTTP_CONTINUE);
6203 printf(&quot;Request status is %d\n&quot;, status);
6204 </PRE>
6205 <H3><A NAME="10_61_6">See Also</A></H3>
6206 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpDelete">
6207  <CODE>httpDelete()</CODE></A>,<A HREF="#httpGet"> <CODE>httpGet()</CODE>
6208 </A>,<A HREF="#httpHead"> <CODE>httpHead()</CODE></A>,<A HREF="#httpOptions">
6209  <CODE>httpOptions()</CODE></A>,<A HREF="#httpPost"> <CODE>httpPost()</CODE>
6210 </A>,<A HREF="#httpPut"> <CODE>httpPut()</CODE></A>,<A HREF="#httpTrace">
6211  <CODE>httpTrace()</CODE></A>
6212 <!-- NEW PAGE -->
6213
6214 <H2><A NAME="httpWrite">httpWrite()</A></H2>
6215 <H3><A NAME="10_62_1">Usage</A></H3>
6216 <PRE>
6217 int httpWrite(http_t *http, char *buffer, int length);
6218 </PRE>
6219 <H3><A NAME="10_62_2">Arguments</A></H3>
6220 <CENTER>
6221 <TABLE BORDER WIDTH="80%">
6222 <TR><TH>Argument</TH><TH>Description</TH></TR>
6223 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6224 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
6225 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
6226 </TABLE>
6227 </CENTER>
6228 <H3><A NAME="10_62_3">Returns</A></H3>
6229 <P>The number of bytes read or -1 on error.</P>
6230 <H3><A NAME="10_62_4">Description</A></H3>
6231 <P>The <CODE>httpWrite()</CODE> function reads data from the HTTP
6232  connection, possibly the result of a GET or POST request.</P>
6233 <H3><A NAME="10_62_5">Example</A></H3>
6234 <PRE>
6235 #include &lt;cups/http.h&gt;
6236
6237 http_t *http;
6238 FILE *fp;
6239 char buffer[1024];
6240 int  bytes;
6241
6242 httpPost(http, &quot;/&quot;);
6243
6244 while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) &gt; 0)
6245   httpWrite(http, buffer, bytes);
6246
6247 while (httpUpdate(http) != HTTP_CONTINUE);
6248
6249 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
6250 {
6251   buffer[bytes] = '\0';
6252   fputs(buffer, stdout);
6253 }
6254 </PRE>
6255 <H3><A NAME="10_62_6">See Also</A></H3>
6256 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpRead">
6257  <CODE>httpRead()</CODE></A>
6258 <!-- NEW PAGE -->
6259
6260 <H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
6261 <H3><A NAME="10_63_1">Usage</A></H3>
6262 <PRE>
6263 ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
6264                                const char *name, char value);
6265 </PRE>
6266 <H3><A NAME="10_63_2">Arguments</A></H3>
6267 <CENTER>
6268 <TABLE BORDER WIDTH="80%">
6269 <TR><TH>Argument</TH><TH>Description</TH></TR>
6270 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6271 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6272 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6273 <TR><TD>value</TD><TD>The boolean value</TD></TR>
6274 </TABLE>
6275 </CENTER>
6276 <H3><A NAME="10_63_3">Returns</A></H3>
6277 <P>A pointer to the new attribute or NULL if the attribute could not be
6278  created.</P>
6279 <H3><A NAME="10_63_4">Description</A></H3>
6280 <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean
6281  attribute value to the specified IPP request.</P>
6282 <H3><A NAME="10_63_5">Example</A></H3>
6283 <PRE>
6284 #include &lt;cups/ipp.h&gt;
6285
6286 ipp_t *ipp;
6287
6288 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;my-jobs&quot;, 1);
6289 </PRE>
6290 <H3><A NAME="10_63_6">See Also</A></H3>
6291 <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate">
6292  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6293 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6294 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6295 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6296  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6297 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6298 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6299 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6300 ippAddStrings()</CODE></A>
6301 <!-- NEW PAGE -->
6302
6303 <H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
6304 <H3><A NAME="10_64_1">Usage</A></H3>
6305 <PRE>
6306 ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
6307                                 const char *name, int num_values,
6308                                 const char *values);
6309 </PRE>
6310 <H3><A NAME="10_64_2">Arguments</A></H3>
6311 <CENTER>
6312 <TABLE BORDER WIDTH="80%">
6313 <TR><TH>Argument</TH><TH>Description</TH></TR>
6314 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6315 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6316 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6317 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6318 <TR><TD>values</TD><TD>The boolean values</TD></TR>
6319 </TABLE>
6320 </CENTER>
6321 <H3><A NAME="10_64_3">Returns</A></H3>
6322 <P>A pointer to the new attribute or NULL if the attribute could not be
6323  created.</P>
6324 <H3><A NAME="10_64_4">Description</A></H3>
6325 <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
6326  attribute values to the specified IPP request. If the <CODE>values</CODE>
6327  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6328  false values is created.</P>
6329 <H3><A NAME="10_64_5">Example</A></H3>
6330 <PRE>
6331 #include &lt;cups/ipp.h&gt;
6332
6333 ipp_t *ipp;
6334 char values[10];
6335
6336 ippAddBooleans(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 10, values);
6337 </PRE>
6338 <H3><A NAME="10_64_6">See Also</A></H3>
6339 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddDate">
6340  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6341 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6342 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6343 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6344  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6345 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6346 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6347 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6348 ippAddStrings()</CODE></A>
6349 <!-- NEW PAGE -->
6350
6351 <H2><A NAME="ippAddDate">ippAddDate()</A></H2>
6352 <H3><A NAME="10_65_1">Usage</A></H3>
6353 <PRE>
6354 ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group,
6355                             const char *name, ipp_uchar_t *value);
6356 </PRE>
6357 <H3><A NAME="10_65_2">Arguments</A></H3>
6358 <CENTER>
6359 <TABLE BORDER WIDTH="80%">
6360 <TR><TH>Argument</TH><TH>Description</TH></TR>
6361 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6362 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6363 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6364 <TR><TD>value</TD><TD>The date value</TD></TR>
6365 </TABLE>
6366 </CENTER>
6367 <H3><A NAME="10_65_3">Returns</A></H3>
6368 <P>A pointer to the new attribute or NULL if the attribute could not be
6369  created.</P>
6370 <H3><A NAME="10_65_4">Description</A></H3>
6371 <P>The <CODE>ippAddDate()</CODE> function adds a single date-time
6372  attribute value to the specified IPP request.</P>
6373 <H3><A NAME="10_65_5">Example</A></H3>
6374 <PRE>
6375 #include &lt;cups/ipp.h&gt;
6376
6377 ipp_t *ipp;
6378
6379 ippAddDate(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;,
6380            ippTimeToDate(time(NULL));
6381 </PRE>
6382 <H3><A NAME="10_65_6">See Also</A></H3>
6383 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6384  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6385 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6386 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6387 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6388  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6389 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6390 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6391 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6392 ippAddStrings()</CODE></A>,<A HREF="#ippTimeToDate"> <CODE>
6393 ippTimeToDate()</CODE></A>
6394 <!-- NEW PAGE -->
6395
6396 <H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
6397 <H3><A NAME="10_66_1">Usage</A></H3>
6398 <PRE>
6399 ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
6400                                ipp_tag_t tag, const char *name,
6401                                int value);
6402 </PRE>
6403 <H3><A NAME="10_66_2">Arguments</A></H3>
6404 <CENTER>
6405 <TABLE BORDER WIDTH="80%">
6406 <TR><TH>Argument</TH><TH>Description</TH></TR>
6407 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6408 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6409 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6410  IPP_TAG_ENUM)</TD></TR>
6411 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6412 <TR><TD>value</TD><TD>The integer value</TD></TR>
6413 </TABLE>
6414 </CENTER>
6415 <H3><A NAME="10_66_3">Returns</A></H3>
6416 <P>A pointer to the new attribute or NULL if the attribute could not be
6417  created.</P>
6418 <H3><A NAME="10_66_4">Description</A></H3>
6419 <P>The <CODE>ippAddInteger()</CODE> function adds a single integer
6420  attribute value to the specified IPP request.</P>
6421 <H3><A NAME="10_66_5">Example</A></H3>
6422 <PRE>
6423 #include &lt;cups/ipp.h&gt;
6424
6425 ipp_t *ipp;
6426
6427 ippAddInteger(ipp, IPP_TAG_OPERATION, &quot;limit&quot;, 100);
6428 </PRE>
6429 <H3><A NAME="10_66_6">See Also</A></H3>
6430 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6431  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6432 ippAddDate()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6433 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6434 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6435  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6436 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6437 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6438 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6439 ippAddStrings()</CODE></A>
6440 <!-- NEW PAGE -->
6441
6442 <H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
6443 <H3><A NAME="10_67_1">Usage</A></H3>
6444 <PRE>
6445 ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
6446                                 ipp_tag_t tag, const char *name,
6447                                 int num_values, const int *values);
6448 </PRE>
6449 <H3><A NAME="10_67_2">Arguments</A></H3>
6450 <CENTER>
6451 <TABLE BORDER WIDTH="80%">
6452 <TR><TH>Argument</TH><TH>Description</TH></TR>
6453 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6454 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6455 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6456  IPP_TAG_ENUM)</TD></TR>
6457 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6458 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6459 <TR><TD>values</TD><TD>The integer values</TD></TR>
6460 </TABLE>
6461 </CENTER>
6462 <H3><A NAME="10_67_3">Returns</A></H3>
6463 <P>A pointer to the new attribute or NULL if the attribute could not be
6464  created.</P>
6465 <H3><A NAME="10_67_4">Description</A></H3>
6466 <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
6467  attribute values to the specified IPP request. If the <CODE>values</CODE>
6468  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> 0
6469  values is created.</P>
6470 <H3><A NAME="10_67_5">Example</A></H3>
6471 <PRE>
6472 #include &lt;cups/ipp.h&gt;
6473
6474 ipp_t *ipp;
6475 int values[100];
6476
6477 ippAddIntegers(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 100, values);
6478 </PRE>
6479 <H3><A NAME="10_67_6">See Also</A></H3>
6480 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6481  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6482 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6483 </A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges">
6484  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6485 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6486 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6487 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6488 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6489 ippAddStrings()</CODE></A>
6490 <!-- NEW PAGE -->
6491
6492 <H2><A NAME="ippAddRange">ippAddRange()</A></H2>
6493 <H3><A NAME="10_68_1">Usage</A></H3>
6494 <PRE>
6495 ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group,
6496                              const char *name, int low,
6497                              int high);
6498 </PRE>
6499 <H3><A NAME="10_68_2">Arguments</A></H3>
6500 <CENTER>
6501 <TABLE BORDER WIDTH="80%">
6502 <TR><TH>Argument</TH><TH>Description</TH></TR>
6503 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6504 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6505 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6506 <TR><TD>low</TD><TD>The lower value</TD></TR>
6507 <TR><TD>high</TD><TD>The higher value</TD></TR>
6508 </TABLE>
6509 </CENTER>
6510 <H3><A NAME="10_68_3">Returns</A></H3>
6511 <P>A pointer to the new attribute or NULL if the attribute could not be
6512  created.</P>
6513 <H3><A NAME="10_68_4">Description</A></H3>
6514 <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
6515  value to the specified IPP request.</P>
6516 <H3><A NAME="10_68_5">Example</A></H3>
6517 <PRE>
6518 #include &lt;cups/ipp.h&gt;
6519
6520 ipp_t *ipp;
6521
6522 ippAddRange(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 1, 10);
6523 </PRE>
6524 <H3><A NAME="10_68_6">See Also</A></H3>
6525 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6526  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6527 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6528 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRanges">
6529  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6530 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6531 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6532 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6533 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6534 ippAddStrings()</CODE></A>
6535 <!-- NEW PAGE -->
6536
6537 <H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
6538 <H3><A NAME="10_69_1">Usage</A></H3>
6539 <PRE>
6540 ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
6541                               const char *name, int num_values,
6542                               const int *lows, const int *highs);
6543 </PRE>
6544 <H3><A NAME="10_69_2">Arguments</A></H3>
6545 <CENTER>
6546 <TABLE BORDER WIDTH="80%">
6547 <TR><TH>Argument</TH><TH>Description</TH></TR>
6548 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6549 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6550 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6551 <TR><TD>num_values</TD><TD>The number of range values</TD></TR>
6552 <TR><TD>lows</TD><TD>The lower values</TD></TR>
6553 <TR><TD>highs</TD><TD>The higher values</TD></TR>
6554 </TABLE>
6555 </CENTER>
6556 <H3><A NAME="10_69_3">Returns</A></H3>
6557 <P>A pointer to the new attribute or NULL if the attribute could not be
6558  created.</P>
6559 <H3><A NAME="10_69_4">Description</A></H3>
6560 <P>The <CODE>ippAddRanges()</CODE> function adds one or more range
6561  attribute values to the specified IPP request. If the <CODE>values</CODE>
6562  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6563  0,0 ranges is created.</P>
6564 <H3><A NAME="10_69_5">Example</A></H3>
6565 <PRE>
6566 #include &lt;cups/ipp.h&gt;
6567
6568 ipp_t *ipp;
6569 int lows[2];
6570 int highs[2];
6571
6572 ippAddRanges(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 2, lows, highs);
6573 </PRE>
6574 <H3><A NAME="10_69_6">See Also</A></H3>
6575 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6576  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6577 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6578 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6579  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6580 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6581 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6582 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6583 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6584 ippAddStrings()</CODE></A>
6585 <!-- NEW PAGE -->
6586
6587 <H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
6588 <H3><A NAME="10_70_1">Usage</A></H3>
6589 <PRE>
6590 ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
6591                                   const char *name, int xres,
6592                                   int yres, ipp_res_t units);
6593 </PRE>
6594 <H3><A NAME="10_70_2">Arguments</A></H3>
6595 <CENTER>
6596 <TABLE BORDER WIDTH="80%">
6597 <TR><TH>Argument</TH><TH>Description</TH></TR>
6598 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6599 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6600 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6601 <TR><TD>xres</TD><TD>The horizontal resolution</TD></TR>
6602 <TR><TD>yres</TD><TD>The vertical resolution</TD></TR>
6603 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6604 </TABLE>
6605 </CENTER>
6606 <H3><A NAME="10_70_3">Returns</A></H3>
6607 <P>A pointer to the new attribute or NULL if the attribute could not be
6608  created.</P>
6609 <H3><A NAME="10_70_4">Description</A></H3>
6610 <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution
6611  attribute value to the specified IPP request.</P>
6612 <H3><A NAME="10_70_5">Example</A></H3>
6613 <PRE>
6614 #include &lt;cups/ipp.h&gt;
6615
6616 ipp_t *ipp;
6617
6618 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolution&quot;,
6619               720, 720, IPP_RES_PER_INCH);
6620 </PRE>
6621 <H3><A NAME="10_70_6">See Also</A></H3>
6622 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6623  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6624 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6625 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6626  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6627 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6628 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6629 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6630 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6631 ippAddStrings()</CODE></A>
6632 <!-- NEW PAGE -->
6633
6634 <H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
6635 <H3><A NAME="10_71_1">Usage</A></H3>
6636 <PRE>
6637 ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
6638                                    const char *name, int num_values,
6639                                    const int *xres, const int *yres,
6640                                    const ipp_res_t *units);
6641 </PRE>
6642 <H3><A NAME="10_71_2">Arguments</A></H3>
6643 <CENTER>
6644 <TABLE BORDER WIDTH="80%">
6645 <TR><TH>Argument</TH><TH>Description</TH></TR>
6646 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6647 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6648 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6649 <TR><TD>num_values</TD><TD>The number of resolution values</TD></TR>
6650 <TR><TD>xres</TD><TD>The horizontal resolutions</TD></TR>
6651 <TR><TD>yres</TD><TD>The vertical resolutions</TD></TR>
6652 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6653 </TABLE>
6654 </CENTER>
6655 <H3><A NAME="10_71_3">Returns</A></H3>
6656 <P>A pointer to the new attribute or NULL if the attribute could not be
6657  created.</P>
6658 <H3><A NAME="10_71_4">Description</A></H3>
6659 <P>The <CODE>ippAddResolutions()</CODE> function adds one or more
6660  resolution attribute values to the specified IPP request. If the <CODE>
6661 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6662 num_values</CODE> 0,0 resolutions is created.</P>
6663 <H3><A NAME="10_71_5">Example</A></H3>
6664 <PRE>
6665 #include &lt;cups/ipp.h&gt;
6666
6667 ipp_t *ipp;
6668 int xres[5];
6669 int yres[5];
6670 ipp_res_t units[5];
6671
6672 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolutions-supported&quot;,
6673               5, xres, yres, units);
6674 </PRE>
6675 <H3><A NAME="10_71_6">See Also</A></H3>
6676 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6677  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6678 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6679 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6680  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6681 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6682 ippAddResolution()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6683 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6684 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6685 ippAddStrings()</CODE></A>
6686 <!-- NEW PAGE -->
6687
6688 <H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
6689 <H3><A NAME="10_72_1">Usage</A></H3>
6690 <PRE>
6691 ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
6692 </PRE>
6693 <H3><A NAME="10_72_2">Arguments</A></H3>
6694 <CENTER>
6695 <TABLE BORDER WIDTH="80%">
6696 <TR><TH>Argument</TH><TH>Description</TH></TR>
6697 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6698 </TABLE>
6699 </CENTER>
6700 <H3><A NAME="10_72_3">Returns</A></H3>
6701 <P>A pointer to the new separator or NULL if the separator could not be
6702  created.</P>
6703 <H3><A NAME="10_72_4">Description</A></H3>
6704 <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator to
6705  the specified IPP request.</P>
6706 <H3><A NAME="10_72_5">Example</A></H3>
6707 <PRE>
6708 #include &lt;cups/ipp.h&gt;
6709
6710 ipp_t *ipp;
6711
6712 ippAddSeparator(ipp);
6713 </PRE>
6714 <H3><A NAME="10_72_6">See Also</A></H3>
6715 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6716  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6717 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6718 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6719  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6720 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6721 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6722 ippAddResolutions()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6723 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6724 ippAddStrings()</CODE></A>
6725 <!-- NEW PAGE -->
6726
6727 <H2><A NAME="ippAddString">ippAddString()</A></H2>
6728 <H3><A NAME="10_73_1">Usage</A></H3>
6729 <PRE>
6730 ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group,
6731                               ipp_tag_t tag, const char *name,
6732                               const char *charset, const char *value);
6733 </PRE>
6734 <H3><A NAME="10_73_2">Arguments</A></H3>
6735 <CENTER>
6736 <TABLE BORDER WIDTH="80%">
6737 <TR><TH>Argument</TH><TH>Description</TH></TR>
6738 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6739 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6740 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6741 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6742 <TR><TD>charset</TD><TD>The character set for the string</TD></TR>
6743 <TR><TD>value</TD><TD>The string value</TD></TR>
6744 </TABLE>
6745 </CENTER>
6746 <H3><A NAME="10_73_3">Returns</A></H3>
6747 <P>A pointer to the new attribute or NULL if the attribute could not be
6748  created.</P>
6749 <H3><A NAME="10_73_4">Description</A></H3>
6750 <P>The <CODE>ippAddString()</CODE> function adds a single string
6751  attribute value to the specified IPP request. For <CODE>
6752 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6753  charset value is provided with the string to identify the string
6754  encoding used. Otherwise the charset value is ignored.</P>
6755 <H3><A NAME="10_73_5">Example</A></H3>
6756 <PRE>
6757 #include &lt;cups/ipp.h&gt;
6758
6759 ipp_t *ipp;
6760
6761 ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;job-name&quot;,
6762              NULL, &quot;abc123&quot;);
6763 </PRE>
6764 <H3><A NAME="10_73_6">See Also</A></H3>
6765 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6766  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6767 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6768 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6769  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6770 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6771 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6772 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6773 ippAddSeparator()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6774 ippAddStrings()</CODE></A>
6775 <!-- NEW PAGE -->
6776
6777 <H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
6778 <H3><A NAME="10_74_1">Usage</A></H3>
6779 <PRE>
6780 ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
6781                                ipp_tag_t tag, const char *name,
6782                                int num_values, const char *charset,
6783                                const char **values);
6784 </PRE>
6785 <H3><A NAME="10_74_2">Arguments</A></H3>
6786 <CENTER>
6787 <TABLE BORDER WIDTH="80%">
6788 <TR><TH>Argument</TH><TH>Description</TH></TR>
6789 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6790 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6791 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6792 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6793 <TR><TD>num_values</TD><TD>The number of strings</TD></TR>
6794 <TR><TD>charset</TD><TD>The character set for the strings</TD></TR>
6795 <TR><TD>values</TD><TD>The string values</TD></TR>
6796 </TABLE>
6797 </CENTER>
6798 <H3><A NAME="10_74_3">Returns</A></H3>
6799 <P>A pointer to the new attribute or NULL if the attribute could not be
6800  created.</P>
6801 <H3><A NAME="10_74_4">Description</A></H3>
6802 <P>The <CODE>ippAddStrings()</CODE> function adds one or more string
6803  attribute values to the specified IPP request. For <CODE>
6804 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6805  charset value is provided with the strings to identify the string
6806  encoding used. Otherwise the charset value is ignored. If the <CODE>
6807 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6808 num_values</CODE> NULL strings is created.</P>
6809 <H3><A NAME="10_74_5">Example</A></H3>
6810 <PRE>
6811 #include &lt;cups/ipp.h&gt;
6812
6813 ipp_t *ipp;
6814 char *values[2] = { &quot;one&quot;, &quot;two&quot; };
6815
6816 ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, &quot;attr-name&quot;,
6817               2, NULL, values);
6818 </PRE>
6819 <H3><A NAME="10_74_6">See Also</A></H3>
6820 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6821  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6822 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6823 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6824  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6825 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6826 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6827 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6828 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6829 ippAddString()</CODE></A>
6830 <!-- NEW PAGE -->
6831
6832 <H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
6833 <H3><A NAME="10_75_1">Usage</A></H3>
6834 <PRE>
6835 time_t ippDateToTime(const ipp_uchar_t date[11]);
6836 </PRE>
6837 <H3><A NAME="10_75_2">Arguments</A></H3>
6838 <CENTER>
6839 <TABLE BORDER WIDTH="80%">
6840 <TR><TH>Argument</TH><TH>Description</TH></TR>
6841 <TR><TD>date</TD><TD>The IPP date-time value</TD></TR>
6842 </TABLE>
6843 </CENTER>
6844 <H3><A NAME="10_75_3">Returns</A></H3>
6845 <P>A UNIX time value.</P>
6846 <H3><A NAME="10_75_4">Description</A></H3>
6847 <P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time
6848  value to a UNIX time value.</P>
6849 <H3><A NAME="10_75_5">Example</A></H3>
6850 <PRE>
6851 #include &lt;cups/ipp.h&gt;
6852
6853 ipp_uchar_t date[11];
6854
6855 printf(&quot;UNIX time is %d\n&quot;, ippDateToTime(date));
6856 </PRE>
6857 <H3><A NAME="10_75_6">See Also</A></H3>
6858 <A HREF="#ippTimeToDate"> <CODE>ippTimeToDate()</CODE></A>
6859 <!-- NEW PAGE -->
6860
6861 <H2><A NAME="ippDelete">ippDelete()</A></H2>
6862 <H3><A NAME="10_76_1">Usage</A></H3>
6863 <PRE>
6864 void ippDelete(ipp_t *ipp);
6865 </PRE>
6866 <H3><A NAME="10_76_2">Arguments</A></H3>
6867 <CENTER>
6868 <TABLE BORDER WIDTH="80%">
6869 <TR><TH>Argument</TH><TH>Description</TH></TR>
6870 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6871 </TABLE>
6872 </CENTER>
6873 <H3><A NAME="10_76_3">Description</A></H3>
6874 <P>The <CODE>ippDelete()</CODE> function deletes all memory used by an
6875  IPP request or response.</P>
6876 <H3><A NAME="10_76_4">Example</A></H3>
6877 <PRE>
6878 #include &lt;cups/ipp.h&gt;
6879
6880 ipp_t *ipp;
6881
6882 ippDelete(ipp);
6883 </PRE>
6884 <H3><A NAME="10_76_5">See Also</A></H3>
6885 <A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6886 <!-- NEW PAGE -->
6887
6888 <H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
6889 <H3><A NAME="10_77_1">Usage</A></H3>
6890 <PRE>
6891 ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);
6892 </PRE>
6893 <H3><A NAME="10_77_2">Arguments</A></H3>
6894 <CENTER>
6895 <TABLE BORDER WIDTH="80%">
6896 <TR><TH>Argument</TH><TH>Description</TH></TR>
6897 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6898 <TR><TD>name</TD><TD>The name of the attribute</TD></TR>
6899 <TR><TD>tag</TD><TD>The required value tag for the attribute or <CODE>
6900 IPP_TAG_ZERO</CODE> for any type of value.</TD></TR>
6901 </TABLE>
6902 </CENTER>
6903 <H3><A NAME="10_77_3">Returns</A></H3>
6904 <P>A pointer to the first occurrence of the requested attribute, or <CODE>
6905 NULL</CODE> if it was not found.</P>
6906 <H3><A NAME="10_77_4">Description</A></H3>
6907 <P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the
6908  named attribute. The <CODE>tag</CODE> parameter restricts the search to
6909  a specific value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value
6910  with the name.</P>
6911 <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
6912  match the name/text values with or without the language code.</P>
6913 <H3><A NAME="10_77_5">Example</A></H3>
6914 <PRE>
6915 ipp_attribute_t *attr;
6916
6917 attr = ippFindAttribute(response, &quot;printer-state-message&quot;, IPP_TAG_TEXT);
6918 </PRE>
6919 <H3><A NAME="10_77_6">See Also</A></H3>
6920 <A HREF="#cupsDoFileRequest"> <CODE>cupsDoFileRequest()</CODE></A>,<A HREF="#cupsDoRequest">
6921  <CODE>cupsDoRequest()</CODE></A>,<A HREF="#ippDelete"> <CODE>
6922 ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6923 <!-- NEW PAGE -->
6924
6925 <H2><A NAME="ippLength">ippLength()</A></H2>
6926 <H3><A NAME="10_78_1">Usage</A></H3>
6927 <PRE>
6928 int ippLength(ipp_t *ipp);
6929 </PRE>
6930 <H3><A NAME="10_78_2">Arguments</A></H3>
6931 <CENTER>
6932 <TABLE BORDER WIDTH="80%">
6933 <TR><TH>Argument</TH><TH>Description</TH></TR>
6934 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6935 </TABLE>
6936 </CENTER>
6937 <H3><A NAME="10_78_3">Returns</A></H3>
6938 <P>The total encoded length of the IPP request or response in bytes.</P>
6939 <H3><A NAME="10_78_4">Description</A></H3>
6940 <P><CODE>ippLength()</CODE> returns the length of the IPP request or
6941  response in bytes.</P>
6942 <H3><A NAME="10_78_5">Example</A></H3>
6943 <PRE>
6944 printf(&quot;The length of the response is %d bytes.\n&quot;, ippLength(response));
6945 </PRE>
6946 <H3><A NAME="10_78_6">See Also</A></H3>
6947 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>
6948 ippNew()</CODE></A>
6949 <!-- NEW PAGE -->
6950
6951 <H2><A NAME="ippNew">ippNew()</A></H2>
6952 <H3><A NAME="10_79_1">Usage</A></H3>
6953 <PRE>
6954 ipp_t *ippNew(void);
6955 </PRE>
6956 <H3><A NAME="10_79_2">Returns</A></H3>
6957 <P>A pointer to a new IPP request or response.</P>
6958 <H3><A NAME="10_79_3">Description</A></H3>
6959 <P>The <CODE>ippNew()</CODE> function creates a new IPP request or
6960  response.</P>
6961 <H3><A NAME="10_79_4">Example</A></H3>
6962 <PRE>
6963 #include &lt;cups/ipp.h&gt;
6964
6965 ipp_t *ipp;
6966
6967 ipp = ippNew();
6968 </PRE>
6969 <H3><A NAME="10_79_5">See Also</A></H3>
6970 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>
6971 <!-- NEW PAGE -->
6972
6973 <H2><A NAME="ippPort">ippPort()</A></H2>
6974 <H3><A NAME="10_80_1">Usage</A></H3>
6975 <PRE>
6976 int ippPort(void);
6977 </PRE>
6978 <H3><A NAME="10_80_2">Returns</A></H3>
6979 <P>The default TCP/IP port number for IPP requests.</P>
6980 <H3><A NAME="10_80_3">Description</A></H3>
6981 <P>The <CODE>ippPort()</CODE> function returns the default IPP port
6982  number for requests.</P>
6983 <H3><A NAME="10_80_4">Example</A></H3>
6984 <PRE>
6985 #include &lt;cups/http.h&gt;
6986 #include &lt;cups/ipp.h&gt;
6987
6988 http_t *http;
6989
6990 http = httpConnect(cupsServer(), ippPort());
6991 </PRE>
6992 <H3><A NAME="10_80_5">See Also</A></H3>
6993 <A HREF="#cupsServer"> <CODE>cupsServer()</CODE></A>,<A HREF="#ippSetPort">
6994  <CODE>ippSetPort()</CODE></A>
6995 <!-- NEW PAGE -->
6996
6997 <H2><A NAME="ippRead">ippRead()</A></H2>
6998 <H3><A NAME="10_81_1">Usage</A></H3>
6999 <PRE>
7000 ipp_state_t ippRead(http_t *http, ipp_t *ipp);
7001 </PRE>
7002 <H3><A NAME="10_81_2">Arguments</A></H3>
7003 <CENTER>
7004 <TABLE BORDER WIDTH="80%">
7005 <TR><TH>Argument</TH><TH>Description</TH></TR>
7006 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
7007 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
7008 </TABLE>
7009 </CENTER>
7010 <H3><A NAME="10_81_3">Returns</A></H3>
7011 <P>The current read state.</P>
7012 <H3><A NAME="10_81_4">Description</A></H3>
7013 <P>The <CODE>ippRead()</CODE> function reads IPP attributes from the
7014  specified HTTP connection. Programs should continue calling <CODE>
7015 ippRead()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
7016  is returned.</P>
7017 <H3><A NAME="10_81_5">Example</A></H3>
7018 <PRE>
7019 #include &lt;cups/http.h&gt;
7020 #include &lt;cups/ipp.h&gt;
7021
7022 http_t *http;
7023 ipp_t *ipp;
7024 ipp_state_t status;
7025
7026 ipp = ippNew();
7027
7028 while ((status = ippRead(http, ipp)) != IPP_ERROR)
7029   if (status == IPP_DATA)
7030     break;
7031
7032 if (status == IPP_DATA)
7033 {
7034   ... read additional non-IPP data using httpRead() ...
7035 }
7036 </PRE>
7037 <H3><A NAME="10_81_6">See Also</A></H3>
7038 <A HREF="#ippWrite"> <CODE>ippWrite()</CODE></A>
7039 <!-- NEW PAGE -->
7040
7041 <H2><A NAME="ippSetPort">ippSetPort()</A></H2>
7042 <H3><A NAME="10_82_1">Usage</A></H3>
7043 <PRE>
7044 void
7045 ippSetPort(int port);
7046 </PRE>
7047 <H3><A NAME="10_82_2">Arguments</A></H3>
7048 <CENTER>
7049 <TABLE BORDER WIDTH="80%">
7050 <TR><TH>Argument</TH><TH>Description</TH></TR>
7051 <TR><TD>port</TD><TD>The port number to use</TD></TR>
7052 </TABLE>
7053 </CENTER>
7054 <H3><A NAME="10_82_3">Description</A></H3>
7055 <P>The <CODE>ippSetPort()</CODE> function sets the default IPP port
7056  number for requests.</P>
7057 <H3><A NAME="10_82_4">Example</A></H3>
7058 <PRE>
7059 #include &lt;cups/http.h&gt;
7060 #include &lt;cups/ipp.h&gt;
7061
7062 ...
7063
7064 ippSetPort(8631);
7065 </PRE>
7066 <H3><A NAME="10_82_5">See Also</A></H3>
7067 <A HREF="#ippPort"> <CODE>ippPort()</CODE></A>
7068 <!-- NEW PAGE -->
7069
7070 <H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
7071 <H3><A NAME="10_83_1">Usage</A></H3>
7072 <PRE>
7073 ipp_uchar_t *ippTimeToDate(time_t time);
7074 </PRE>
7075 <H3><A NAME="10_83_2">Arguments</A></H3>
7076 <CENTER>
7077 <TABLE BORDER WIDTH="80%">
7078 <TR><TH>Argument</TH><TH>Description</TH></TR>
7079 <TR><TD>time</TD><TD>The UNIX time value</TD></TR>
7080 </TABLE>
7081 </CENTER>
7082 <H3><A NAME="10_83_3">Returns</A></H3>
7083 <P>A static pointer to an IPP date-time value.</P>
7084 <H3><A NAME="10_83_4">Description</A></H3>
7085 <P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an
7086  IPP date-time value.</P>
7087 <H3><A NAME="10_83_5">Example</A></H3>
7088 <PRE>
7089 #include &lt;cups/ipp.h&gt;
7090
7091 ipp_uchar_t *date;
7092
7093 date = ippTimeToDate(time(NULL));
7094 </PRE>
7095 <H3><A NAME="10_83_6">See Also</A></H3>
7096 <A HREF="#ippDateToTime"> <CODE>ippDateToTime()</CODE></A>
7097 <!-- NEW PAGE -->
7098
7099 <H2><A NAME="ippWrite">ippWrite()</A></H2>
7100 <H3><A NAME="10_84_1">Usage</A></H3>
7101 <PRE>
7102 ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
7103 </PRE>
7104 <H3><A NAME="10_84_2">Arguments</A></H3>
7105 <CENTER>
7106 <TABLE BORDER WIDTH="80%">
7107 <TR><TH>Argument</TH><TH>Description</TH></TR>
7108 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
7109 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
7110 </TABLE>
7111 </CENTER>
7112 <H3><A NAME="10_84_3">Returns</A></H3>
7113 <P>The current write state.</P>
7114 <H3><A NAME="10_84_4">Description</A></H3>
7115 <P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the
7116  specified HTTP connection. Programs should continue calling <CODE>
7117 ippWrite()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
7118  is returned.</P>
7119 <H3><A NAME="10_84_5">Example</A></H3>
7120 <PRE>
7121 #include &lt;cups/http.h&gt;
7122 #include &lt;cups/ipp.h&gt;
7123
7124 http_t *http;
7125 ipp_t *ipp;
7126 ipp_state_t status;
7127
7128 ipp = ippNew();
7129 ... add attributes ...
7130
7131 while ((status = ippWrite(http, ipp)) != IPP_ERROR)
7132   if (status == IPP_DATA)
7133     break;
7134
7135 if (status == IPP_DATA)
7136 {
7137   ... read additional non-IPP data using httpWrite() ...
7138 }
7139 </PRE>
7140 <H3><A NAME="10_84_6">See Also</A></H3>
7141 <A HREF="#ippRead"> <CODE>ippRead()</CODE></A>
7142 <!-- NEW PAGE -->
7143
7144 <H2><A NAME="ppdClose">ppdClose()</A></H2>
7145 <H3><A NAME="10_85_1">Usage</A></H3>
7146 <PRE>
7147 void ppdClose(ppd_file_t *ppd);
7148 </PRE>
7149 <H3><A NAME="10_85_2">Arguments</A></H3>
7150 <CENTER>
7151 <TABLE BORDER WIDTH="80%">
7152 <TR><TH>Argument</TH><TH>Description</TH></TR>
7153 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7154 </TABLE>
7155 </CENTER>
7156 <H3><A NAME="10_85_3">Description</A></H3>
7157 <P>The <CODE>ppdClose()</CODE> function frees all memory associated with
7158  the PPD file.</P>
7159 <H3><A NAME="10_85_4">Example</A></H3>
7160 <PRE>
7161 #include &lt;cups/ppd.h&gt;
7162
7163 ppd_file_t *ppd;
7164
7165 ppdClose(ppd);
7166 </PRE>
7167 <H3><A NAME="10_85_5">See Also</A></H3>
7168 <A HREF="#ppdOpen"> <CODE>ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
7169 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
7170 </A>
7171 <!-- NEW PAGE -->
7172
7173 <H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
7174 <H3><A NAME="10_86_1">Usage</A></H3>
7175 <PRE>
7176 int ppdConflicts(ppd_file_t *ppd);
7177 </PRE>
7178 <H3><A NAME="10_86_2">Arguments</A></H3>
7179 <CENTER>
7180 <TABLE BORDER WIDTH="80%">
7181 <TR><TH>Argument</TH><TH>Description</TH></TR>
7182 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7183 </TABLE>
7184 </CENTER>
7185 <H3><A NAME="10_86_3">Returns</A></H3>
7186 <P>The number of option conflicts in the file.</P>
7187 <H3><A NAME="10_86_4">Description</A></H3>
7188 <P>The <CODE>ppdConflicts()</CODE> function returns the number of
7189  conflicts with the currently selected options.</P>
7190 <H3><A NAME="10_86_5">Example</A></H3>
7191 <PRE>
7192 #include &lt;cups/ppd.h&gt;
7193
7194 ppd_file_t *ppd;
7195
7196 printf(&quot;%d conflicts\n&quot;, ppdConflicts(ppd));
7197 </PRE>
7198 <H3><A NAME="10_86_6">See Also</A></H3>
7199 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdIsMarked">
7200  <CODE>ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7201 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7202 ppdMarkOption()</CODE></A>
7203 <!-- NEW PAGE -->
7204
7205 <H2><A NAME="ppdEmit">ppdEmit()</A></H2>
7206 <H3><A NAME="10_87_1">Usage</A></H3>
7207 <PRE>
7208 int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);
7209 </PRE>
7210 <H3><A NAME="10_87_2">Arguments</A></H3>
7211 <CENTER>
7212 <TABLE BORDER WIDTH="80%">
7213 <TR><TH>Argument</TH><TH>Description</TH></TR>
7214 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7215 <TR><TD>file</TD><TD>The file to write to</TD></TR>
7216 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7217 </TABLE>
7218 </CENTER>
7219 <H3><A NAME="10_87_3">Returns</A></H3>
7220 <P>0 on success, -1 on error.</P>
7221 <H3><A NAME="10_87_4">Description</A></H3>
7222 <P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
7223  commands to the specified file.</P>
7224 <H3><A NAME="10_87_5">Example</A></H3>
7225 <PRE>
7226 #include &lt;cups/ppd.h&gt;
7227
7228 ppd_file_t *ppd;
7229
7230 ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
7231 </PRE>
7232 <H3><A NAME="10_87_6">See Also</A></H3>
7233 <A HREF="#ppdEmitFd"> <CODE>ppdEmitFd()</CODE></A>
7234 <!-- NEW PAGE -->
7235
7236 <H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
7237 <H3><A NAME="10_88_1">Usage</A></H3>
7238 <PRE>
7239 int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);
7240 </PRE>
7241 <H3><A NAME="10_88_2">Arguments</A></H3>
7242 <CENTER>
7243 <TABLE BORDER WIDTH="80%">
7244 <TR><TH>Argument</TH><TH>Description</TH></TR>
7245 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7246 <TR><TD>fd</TD><TD>The file descriptor to write to</TD></TR>
7247 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7248 </TABLE>
7249 </CENTER>
7250 <H3><A NAME="10_88_3">Returns</A></H3>
7251 <P>0 on success, -1 on error.</P>
7252 <H3><A NAME="10_88_4">Description</A></H3>
7253 <P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
7254  commands to the specified file descriptor.</P>
7255 <H3><A NAME="10_88_5">Example</A></H3>
7256 <PRE>
7257 #include &lt;cups/ppd.h&gt;
7258
7259 ppd_file_t *ppd;
7260
7261 ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
7262 </PRE>
7263 <H3><A NAME="10_88_6">See Also</A></H3>
7264 <A HREF="#ppdEmit"> <CODE>ppdEmit()</CODE></A>
7265 <!-- NEW PAGE -->
7266
7267 <H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
7268 <H3><A NAME="10_89_1">Usage</A></H3>
7269 <PRE>
7270 ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);
7271 </PRE>
7272 <H3><A NAME="10_89_2">Arguments</A></H3>
7273 <CENTER>
7274 <TABLE BORDER WIDTH="80%">
7275 <TR><TH>Argument</TH><TH>Description</TH></TR>
7276 <TR><TD>option</TD><TD>A pointer to the option</TD></TR>
7277 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7278 </TABLE>
7279 </CENTER>
7280 <H3><A NAME="10_89_3">Returns</A></H3>
7281 <P>A pointer to the choice data or NULL if the choice does not exist.</P>
7282 <H3><A NAME="10_89_4">Description</A></H3>
7283 <P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the
7284  choice data for the specified option.</P>
7285 <H3><A NAME="10_89_5">Example</A></H3>
7286 <PRE>
7287 #include &lt;cups/ppd.h&gt;
7288
7289 ppd_file_t *ppd;
7290 ppd_option_t *option;
7291 ppd_choice_t *choice;
7292
7293 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7294 choice = ppdFindChoice(option, &quot;Letter&quot;);
7295 </PRE>
7296 <H3><A NAME="10_89_6">See Also</A></H3>
7297 <A HREF="#ppdFindMarkedChoice"> <CODE>ppdFindMarkedChoice()</CODE></A>,<A
7298 HREF="#ppdFindOption"> <CODE>ppdFindOption()</CODE></A>
7299 <!-- NEW PAGE -->
7300
7301 <H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
7302 <H3><A NAME="10_90_1">Usage</A></H3>
7303 <PRE>
7304 ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
7305 </PRE>
7306 <H3><A NAME="10_90_2">Arguments</A></H3>
7307 <CENTER>
7308 <TABLE BORDER WIDTH="80%">
7309 <TR><TH>Argument</TH><TH>Description</TH></TR>
7310 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7311 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7312 </TABLE>
7313 </CENTER>
7314 <H3><A NAME="10_90_3">Returns</A></H3>
7315 <P>A pointer to the choice data or NULL if the choice does not exist or
7316  is not marked.</P>
7317 <H3><A NAME="10_90_4">Description</A></H3>
7318 <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
7319  the marked choice data for the specified option.</P>
7320 <H3><A NAME="10_90_5">Example</A></H3>
7321 <PRE>
7322 #include &lt;cups/ppd.h&gt;
7323
7324 ppd_file_t *ppd;
7325 ppd_choice_t *choice;
7326
7327 choice = ppdFindMarkedChoice(ppd, &quot;PageSize&quot;);
7328 </PRE>
7329 <H3><A NAME="10_90_6">See Also</A></H3>
7330 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindOption">
7331  <CODE>ppdFindOption()</CODE></A>
7332 <!-- NEW PAGE -->
7333
7334 <H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
7335 <H3><A NAME="10_91_1">Usage</A></H3>
7336 <PRE>
7337 ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
7338 </PRE>
7339 <H3><A NAME="10_91_2">Arguments</A></H3>
7340 <CENTER>
7341 <TABLE BORDER WIDTH="80%">
7342 <TR><TH>Argument</TH><TH>Description</TH></TR>
7343 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7344 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7345 </TABLE>
7346 </CENTER>
7347 <H3><A NAME="10_91_3">Returns</A></H3>
7348 <P>A pointer to the option data or NULL if the option does not exist.</P>
7349 <H3><A NAME="10_91_4">Description</A></H3>
7350 <P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the
7351  option data for the specified option.</P>
7352 <H3><A NAME="10_91_5">Example</A></H3>
7353 <PRE>
7354 #include &lt;cups/ppd.h&gt;
7355
7356 ppd_file_t *ppd;
7357 ppd_option_t *option;
7358
7359 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7360 </PRE>
7361 <H3><A NAME="10_91_6">See Also</A></H3>
7362 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindMarkedChoice">
7363  <CODE>ppdFindMarkedChoice()</CODE></A>
7364 <!-- NEW PAGE -->
7365
7366 <H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
7367 <H3><A NAME="10_92_1">Usage</A></H3>
7368 <PRE>
7369 int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);
7370 </PRE>
7371 <H3><A NAME="10_92_2">Arguments</A></H3>
7372 <CENTER>
7373 <TABLE BORDER WIDTH="80%">
7374 <TR><TH>Argument</TH><TH>Description</TH></TR>
7375 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7376 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7377 <TR><TD>choice</TD><TD>The name of the option choice</TD></TR>
7378 </TABLE>
7379 </CENTER>
7380 <H3><A NAME="10_92_3">Returns</A></H3>
7381 <P>1 if the choice is marked, 0 otherwise.</P>
7382 <H3><A NAME="10_92_4">Description</A></H3>
7383 <P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
7384  specified option choice is marked.</P>
7385 <H3><A NAME="10_92_5">Example</A></H3>
7386 <PRE>
7387 #include &lt;cups/ppd.h&gt;
7388
7389 ppd_file_t *ppd;
7390
7391 printf(&quot;Letter size %s selected.\n&quot;,
7392        ppdIsMarked(ppd, &quot;PageSize&quot;, &quot;Letter&quot;) ? &quot;is&quot; : &quot;is not&quot;);
7393 </PRE>
7394 <H3><A NAME="10_92_6">See Also</A></H3>
7395 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7396  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7397 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7398 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7399 ppdMarkOption()</CODE></A>
7400 <!-- NEW PAGE -->
7401
7402 <H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
7403 <H3><A NAME="10_93_1">Usage</A></H3>
7404 <PRE>
7405 void ppdMarkDefaults(ppd_file_t *ppd);
7406 </PRE>
7407 <H3><A NAME="10_93_2">Arguments</A></H3>
7408 <CENTER>
7409 <TABLE BORDER WIDTH="80%">
7410 <TR><TH>Argument</TH><TH>Description</TH></TR>
7411 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7412 </TABLE>
7413 </CENTER>
7414 <H3><A NAME="10_93_3">Description</A></H3>
7415 <P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
7416  choices in the PPD file.</P>
7417 <H3><A NAME="10_93_4">Example</A></H3>
7418 <PRE>
7419 #include &lt;cups/ppd.h&gt;
7420
7421 ppd_file_t *ppd;
7422
7423 ppdMarkDefaults(ppd);
7424 </PRE>
7425 <H3><A NAME="10_93_5">See Also</A></H3>
7426 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7427  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7428 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7429 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7430 ppdMarkOption()</CODE></A>
7431 <!-- NEW PAGE -->
7432
7433 <H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
7434 <H3><A NAME="10_94_1">Usage</A></H3>
7435 <PRE>
7436 int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);
7437 </PRE>
7438 <H3><A NAME="10_94_2">Arguments</A></H3>
7439 <CENTER>
7440 <TABLE BORDER WIDTH="80%">
7441 <TR><TH>Argument</TH><TH>Description</TH></TR>
7442 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7443 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7444 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7445 </TABLE>
7446 </CENTER>
7447 <H3><A NAME="10_94_3">Returns</A></H3>
7448 <P>The number of conflicts in the PPD file.</P>
7449 <H3><A NAME="10_94_4">Description</A></H3>
7450 <P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
7451  choice.</P>
7452 <H3><A NAME="10_94_5">Example</A></H3>
7453 <PRE>
7454 #include &lt;cups/ppd.h&gt;
7455
7456 ppd_file_t *ppd;
7457
7458 ppdMarkOption(ppd, &quot;PageSize&quot;, &quot;Letter&quot;);
7459 </PRE>
7460 <H3><A NAME="10_94_6">See Also</A></H3>
7461 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7462  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7463 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7464 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7465 ppdMarkOption()</CODE></A>
7466 <!-- NEW PAGE -->
7467
7468 <H2><A NAME="ppdOpen">ppdOpen()</A></H2>
7469 <H3><A NAME="10_95_1">Usage</A></H3>
7470 <PRE>
7471 ppd_file_t *ppdOpen(FILE *file);
7472 </PRE>
7473 <H3><A NAME="10_95_2">Arguments</A></H3>
7474 <CENTER>
7475 <TABLE BORDER WIDTH="80%">
7476 <TR><TH>Argument</TH><TH>Description</TH></TR>
7477 <TR><TD>file</TD><TD>The file to read from</TD></TR>
7478 </TABLE>
7479 </CENTER>
7480 <H3><A NAME="10_95_3">Returns</A></H3>
7481 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7482  be read.</P>
7483 <H3><A NAME="10_95_4">Description</A></H3>
7484 <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the
7485  specified file into memory.</P>
7486 <H3><A NAME="10_95_5">Example</A></H3>
7487 <PRE>
7488 #include &lt;cups/ppd.h&gt;
7489
7490 ppd_file_t *ppd;
7491 FILE *file;
7492
7493 file = fopen(&quot;filename.ppd&quot;, &quot;rb&quot;);
7494 ppd = ppdOpen(file);
7495 fclose(file);
7496 </PRE>
7497 <H3><A NAME="10_95_6">See Also</A></H3>
7498 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
7499 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
7500 </A>
7501 <!-- NEW PAGE -->
7502
7503 <H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
7504 <H3><A NAME="10_96_1">Usage</A></H3>
7505 <PRE>
7506 ppd_file_t *ppdOpenFd(int fd);
7507 </PRE>
7508 <H3><A NAME="10_96_2">Arguments</A></H3>
7509 <CENTER>
7510 <TABLE BORDER WIDTH="80%">
7511 <TR><TH>Argument</TH><TH>Description</TH></TR>
7512 <TR><TD>fd</TD><TD>The file descriptor to read from</TD></TR>
7513 </TABLE>
7514 </CENTER>
7515 <H3><A NAME="10_96_3">Returns</A></H3>
7516 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7517  be read.</P>
7518 <H3><A NAME="10_96_4">Description</A></H3>
7519 <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the
7520  specified file descriptor into memory.</P>
7521 <H3><A NAME="10_96_5">Example</A></H3>
7522 <PRE>
7523 #include &lt;cups/ppd.h&gt;
7524
7525 ppd_file_t *ppd;
7526 int        fd;
7527
7528 fd = open(&quot;filename.ppd&quot;, O_RDONLY);
7529 ppd = ppdOpenFd(fd);
7530 close(fd);
7531 </PRE>
7532 <H3><A NAME="10_96_6">See Also</A></H3>
7533 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7534 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE></A>
7535 <!-- NEW PAGE -->
7536
7537 <H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
7538 <H3><A NAME="10_97_1">Usage</A></H3>
7539 <PRE>
7540 ppd_file_t *ppdOpenFile(const char *filename);
7541 </PRE>
7542 <H3><A NAME="10_97_2">Arguments</A></H3>
7543 <CENTER>
7544 <TABLE BORDER WIDTH="80%">
7545 <TR><TH>Argument</TH><TH>Description</TH></TR>
7546 <TR><TD>filename</TD><TD>The name of the file to read from</TD></TR>
7547 </TABLE>
7548 </CENTER>
7549 <H3><A NAME="10_97_3">Returns</A></H3>
7550 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7551  be read.</P>
7552 <H3><A NAME="10_97_4">Description</A></H3>
7553 <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the
7554  named file into memory.</P>
7555 <H3><A NAME="10_97_5">Example</A></H3>
7556 <PRE>
7557 #include &lt;cups/ppd.h&gt;
7558
7559 ppd_file_t *ppd;
7560
7561 ppd = ppdOpenFile(&quot;filename.ppd&quot;);
7562 </PRE>
7563 <H3><A NAME="10_97_6">See Also</A></H3>
7564 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7565 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>ppdOpenFd()</CODE></A>
7566 <!-- NEW PAGE -->
7567
7568 <H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
7569 <H3><A NAME="10_98_1">Usage</A></H3>
7570 <PRE>
7571 float ppdPageLength(ppd_file_t *ppd, const char *name);
7572 </PRE>
7573 <H3><A NAME="10_98_2">Arguments</A></H3>
7574 <CENTER>
7575 <TABLE BORDER WIDTH="80%">
7576 <TR><TH>Argument</TH><TH>Description</TH></TR>
7577 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7578 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7579 </TABLE>
7580 </CENTER>
7581 <H3><A NAME="10_98_3">Returns</A></H3>
7582 <P>The length of the specified page size in points or 0 if the page size
7583  does not exist.</P>
7584 <H3><A NAME="10_98_4">Description</A></H3>
7585 <P>The <CODE>ppdPageLength()</CODE> function returns the page length of
7586  the specified page size.</P>
7587 <H3><A NAME="10_98_5">Example</A></H3>
7588 <PRE>
7589 #include &lt;cups/ppd.h&gt;
7590
7591 ppd_file_t *ppd;
7592
7593 printf(&quot;Length = %.0f\n&quot;, ppdPageLength(ppd, &quot;Letter&quot;));
7594 </PRE>
7595 <H3><A NAME="10_98_6">See Also</A></H3>
7596 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7597  <CODE>ppdPageSize()</CODE></A>,<A HREF="#ppdPageWidth"> <CODE>
7598 ppdPageWidth()</CODE></A>
7599 <!-- NEW PAGE -->
7600
7601 <H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
7602 <H3><A NAME="10_99_1">Usage</A></H3>
7603 <PRE>
7604 ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
7605 </PRE>
7606 <H3><A NAME="10_99_2">Arguments</A></H3>
7607 <CENTER>
7608 <TABLE BORDER WIDTH="80%">
7609 <TR><TH>Argument</TH><TH>Description</TH></TR>
7610 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7611 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7612 </TABLE>
7613 </CENTER>
7614 <H3><A NAME="10_99_3">Returns</A></H3>
7615 <P>A pointer to the page size record of the specified page size in
7616  points or NULL if the page size does not exist.</P>
7617 <H3><A NAME="10_99_4">Description</A></H3>
7618 <P>The <CODE>ppdPageSize()</CODE> function returns the page size record
7619  for the specified page size.</P>
7620 <H3><A NAME="10_99_5">Example</A></H3>
7621 <PRE>
7622 #include &lt;cups/ppd.h&gt;
7623
7624 ppd_file_t *ppd;
7625 ppd_size_t *size;
7626
7627 size = ppdPageSize(ppd, &quot;Letter&quot;);
7628 if (size != NULL)
7629 {
7630   printf(&quot; Width = %.0f\n&quot;, size-&gt;width);
7631   printf(&quot;Length = %.0f\n&quot;, size-&gt;length);
7632   printf(&quot;  Left = %.0f\n&quot;, size-&gt;left);
7633   printf(&quot; Right = %.0f\n&quot;, size-&gt;right);
7634   printf(&quot;Bottom = %.0f\n&quot;, size-&gt;bottom);
7635   printf(&quot;   Top = %.0f\n&quot;, size-&gt;top);
7636 }
7637 </PRE>
7638 <H3><A NAME="10_99_6">See Also</A></H3>
7639 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageWidth">
7640  <CODE>ppdPageWidth()</CODE></A>
7641 <!-- NEW PAGE -->
7642
7643 <H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
7644 <H3><A NAME="10_100_1">Usage</A></H3>
7645 <PRE>
7646 float ppdPageWidth(ppd_file_t *ppd, const char *name);
7647 </PRE>
7648 <H3><A NAME="10_100_2">Arguments</A></H3>
7649 <CENTER>
7650 <TABLE BORDER WIDTH="80%">
7651 <TR><TH>Argument</TH><TH>Description</TH></TR>
7652 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7653 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7654 </TABLE>
7655 </CENTER>
7656 <H3><A NAME="10_100_3">Returns</A></H3>
7657 <P>The width of the specified page size in points or 0 if the page size
7658  does not exist.</P>
7659 <H3><A NAME="10_100_4">Description</A></H3>
7660 <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of
7661  the specified page size.</P>
7662 <H3><A NAME="10_100_5">Example</A></H3>
7663 <PRE>
7664 #include &lt;cups/ppd.h&gt;
7665
7666 ppd_file_t *ppd;
7667
7668 printf(&quot;Width = %.0f\n&quot;, ppdPageWidth(ppd, &quot;Letter&quot;));
7669 </PRE>
7670 <H3><A NAME="10_100_6">See Also</A></H3>
7671 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7672  <CODE>ppdPageSize()</CODE></A></BODY>
7673 </HTML>