doc/help/api-overview.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5 <title>Introduction to CUPS Programming</title>
   6 <meta name="keywords" content="Programming">
   7 <meta name="creator" content="Mini-XML v2.6">
   8 <style type="text/css"><!--
   9 BODY {
  10   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  11 }
  12
  13 H1, H2, H3, H4, H5, H6, P, TD, TH {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 KBD {
  18   font-family: monaco, courier, monospace;
  19   font-weight: bold;
  20 }
  21
  22 PRE {
  23   font-family: monaco, courier, monospace;
  24 }
  25
  26 PRE.command {
  27   margin-left: 36pt;
  28 }
  29
  30 P.compact {
  31   margin: 0;
  32 }
  33
  34 P.example {
  35   font-style: italic;
  36   margin-left: 36pt;
  37 }
  38
  39 PRE.example {
  40   background: #eeeeee;
  41   border: dotted thin #999999;
  42   margin-left: 36pt;
  43   padding: 10pt;
  44 }
  45
  46 PRE.command EM, PRE.example EM {
  47   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  48 }
  49
  50 P.command {
  51   font-family: monaco, courier, monospace;
  52   margin-left: 36pt;
  53 }
  54
  55 P.formula {
  56   font-style: italic;
  57   margin-left: 36pt;
  58 }
  59
  60 BLOCKQUOTE {
  61   background: #eeeeee;
  62   border: solid thin #999999;
  63   padding: 10pt;
  64 }
  65
  66 A IMG {
  67   border: none;
  68 }
  69
  70 A:link:hover IMG {
  71   background: #f0f0f0;
  72   border-radius: 10px;
  73   -moz-border-radius: 10px;
  74 }
  75
  76 A:link, A:visited {
  77   font-weight: normal;
  78   text-decoration: none;
  79 }
  80
  81 A:link:hover, A:visited:hover, A:active {
  82   text-decoration: underline;
  83 }
  84
  85 SUB, SUP {
  86   font-size: 50%;
  87 }
  88
  89 TR.data, TD.data, TR.data TD {
  90   margin-top: 10pt;
  91   padding: 5pt;
  92   border-bottom: solid 1pt #999999;
  93 }
  94
  95 TR.data TH {
  96   border-bottom: solid 1pt #999999;
  97   padding-top: 10pt;
  98   padding-left: 5pt;
  99   text-align: left;
 100 }
 101
 102 DIV.table TABLE {
 103   border: solid thin #999999;
 104   border-collapse: collapse;
 105   border-spacing: 0;
 106   margin-left: auto;
 107   margin-right: auto;
 108 }
 109
 110 DIV.table CAPTION {
 111   caption-side: top;
 112   font-size: 120%;
 113   font-style: italic;
 114   font-weight: bold;
 115   margin-left: auto;
 116   margin-right: auto;
 117 }
 118
 119 DIV.table TABLE TD {
 120   border: solid thin #cccccc;
 121   padding-top: 5pt;
 122 }
 123
 124 DIV.table TABLE TH {
 125   background: #cccccc;
 126   border: none;
 127   border-bottom: solid thin #999999;
 128 }
 129
 130 DIV.figure TABLE {
 131   margin-left: auto;
 132   margin-right: auto;
 133 }
 134
 135 DIV.figure CAPTION {
 136   caption-side: bottom;
 137   font-size: 120%;
 138   font-style: italic;
 139   font-weight: bold;
 140   margin-left: auto;
 141   margin-right: auto;
 142 }
 143
 144 TH.label {
 145   text-align: right;
 146   vertical-align: top;
 147 }
 148
 149 TH.sublabel {
 150   text-align: right;
 151   font-weight: normal;
 152 }
 153
 154 HR {
 155   border: solid thin;
 156 }
 157
 158 SPAN.info {
 159   background: black;
 160   border: thin solid black;
 161   color: white;
 162   font-size: 80%;
 163   font-style: italic;
 164   font-weight: bold;
 165   white-space: nowrap;
 166 }
 167
 168 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 169   float: right;
 170   font-size: 100%;
 171 }
 172
 173 H1.title {
 174 }
 175
 176 H2.title, H3.title {
 177   border-bottom: solid 2pt #000000;
 178 }
 179
 180 DIV.indent, TABLE.indent {
 181   margin-top: 2em;
 182   margin-left: auto;
 183   margin-right: auto;
 184   width: 90%;
 185 }
 186
 187 TABLE.indent {
 188   border-collapse: collapse;
 189 }
 190
 191 TABLE.indent TD, TABLE.indent TH {
 192   padding: 0;
 193 }
 194
 195 TABLE.list {
 196   border-collapse: collapse;
 197   margin-left: auto;
 198   margin-right: auto;
 199   width: 90%;
 200 }
 201
 202 TABLE.list TH {
 203   background: white;
 204   border-bottom: solid thin #cccccc;
 205   color: #444444;
 206   padding-top: 10pt;
 207   padding-left: 5pt;
 208   text-align: left;
 209   vertical-align: bottom;
 210   white-space: nowrap;
 211 }
 212
 213 TABLE.list TH A {
 214   color: #4444cc;
 215 }
 216
 217 TABLE.list TD {
 218   border-bottom: solid thin #eeeeee;
 219   padding-top: 5pt;
 220   padding-left: 5pt;
 221 }
 222
 223 TABLE.list TR:nth-child(even) {
 224   background: #f8f8f8;
 225 }
 226
 227 TABLE.list TR:nth-child(odd) {
 228   background: #f4f4f4;
 229 }
 230
 231 DT {
 232   margin-left: 36pt;
 233   margin-top: 12pt;
 234 }
 235
 236 DD {
 237   margin-left: 54pt;
 238 }
 239
 240 DL.category DT {
 241   font-weight: bold;
 242 }
 243
 244 P.summary {
 245   margin-left: 36pt;
 246   font-family: monaco, courier, monospace;
 247 }
 248
 249 DIV.summary TABLE {
 250   border: solid thin #999999;
 251   border-collapse: collapse;
 252   border-spacing: 0;
 253   margin: 10px;
 254 }
 255
 256 DIV.summary TABLE TD, DIV.summary TABLE TH {
 257   border: solid thin #999999;
 258   padding: 5px;
 259   text-align: left;
 260   vertical-align: top;
 261 }
 262
 263 DIV.summary TABLE THEAD TH {
 264   background: #eeeeee;
 265 }
 266
 267 /* API documentation styles... */
 268 div.body h1 {
 269   margin: 0;
 270 }
 271 div.body h2 {
 272   margin-top: 1.5em;
 273 }
 274 div.body h3, div.body h4, div.body h5 {
 275   margin-bottom: 0.5em;
 276   margin-top: 1.5em;
 277 }
 278 .class, .enumeration, .function, .struct, .typedef, .union {
 279   border-bottom: solid thin #999999;
 280   margin-bottom: 0;
 281   margin-top: 2em;
 282 }
 283 .description {
 284   margin-top: 0.5em;
 285 }
 286 code, p.code, pre, ul.code li {
 287   font-family: monaco, courier, monospace;
 288   font-size: 90%;
 289 }
 290 ul.code, ul.contents, ul.subcontents {
 291   list-style-type: none;
 292   margin: 0;
 293   padding-left: 0;
 294 }
 295 ul.code li {
 296   margin: 0;
 297 }
 298 ul.contents > li {
 299   margin-top: 1em;
 300 }
 301 ul.contents li ul.code, ul.contents li ul.subcontents {
 302   padding-left: 2em;
 303 }
 304 div.body dl {
 305   margin-left: 0;
 306   margin-top: 0;
 307 }
 308 div.body dt {
 309   font-style: italic;
 310   margin-left: 0;
 311   margin-top: 0;
 312 }
 313 div.body dd {
 314   margin-bottom: 0.5em;
 315 }
 316
 317 /* This is just for the HTML files generated with the framedhelp target */
 318 div.contents {
 319   background: #e8e8e8;
 320   border: solid thin black;
 321   padding: 10px;
 322 }
 323 div.contents h1 {
 324   font-size: 110%;
 325 }
 326 div.contents h2 {
 327   font-size: 100%;
 328 }
 329 div.contents ul.contents {
 330   font-size: 80%;
 331 }
 332 div.contents ul.subcontents li {
 333   margin-left: 1em;
 334   text-indent: -1em;
 335 }
 336 --></style>
 337 </head>
 338 <body>
 339 <div class='body'>
 340 <!--
 341   "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
 342
 343   Introduction to CUPS programming header for the Common UNIX Printing System
 344   (CUPS).
 345
 346   Copyright 2008-2009 by Apple Inc.
 347
 348   These coded instructions, statements, and computer programs are the
 349   property of Apple Inc. and are protected by Federal copyright
 350   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 351   which should have been included with this file.  If this file is
 352   file is missing or damaged, see the license at "http://www.cups.org/".
 353 -->
 354
 355 <h1 class='title'>Introduction to CUPS Programming</h1>
 356
 357 <div class='summary'><table summary='General Information'>
 358 <thead>
 359 <tr>
 360         <th>Headers</th>
 361         <th>cups/cups.h<br>
 362         cups/array.h<br>
 363         cups/backend.h<br>
 364         cups/dir.h<br>
 365         cups/file.h<br>
 366         cups/ppd.h<br>
 367         cups/raster.h<br>
 368         cups/sidechannel.h</th>
 369 </tr>
 370 </thead>
 371 <tbody>
 372 <tr>
 373         <th>Libraries</th>
 374         <td>-lcups<br>
 375         -lcupsimage</td>
 376 </tr>
 377 <tr>
 378         <th>See Also</th>
 379         <td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
 380         Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
 381         Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
 382         Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
 383         Programming: <a href='api-array.html' target='_top'>Array API</a><br>
 384         Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
 385         Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
 386         Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
 387         Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
 388         Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
 389         References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
 390         Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
 391 </tr>
 392 </tbody>
 393 </table></div>
 394 <h2 class="title">Contents</h2>
 395 <ul class="contents">
 396 <ul class="subcontents">
 397 <li><a href="#OVERVIEW">Overview</a></li>
 398 <li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
 399 <li><a href="#XCODE">Compiling with Xcode</a></li>
 400 <li><a href="#COMMANDLINE">Compiling with GCC</a></li>
 401 </ul></li>
 402 <li><a href="#WHERETOGO">Where to Go Next</a></li>
 403 <!--
 404   "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
 405
 406   Introduction to CUPS programming content for the Common UNIX Printing System
 407   (CUPS).
 408
 409   Copyright 2008 by Apple Inc.
 410
 411   These coded instructions, statements, and computer programs are the
 412   property of Apple Inc. and are protected by Federal copyright
 413   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 414   which should have been included with this file.  If this file is
 415   file is missing or damaged, see the license at "http://www.cups.org/".
 416 -->
 417
 418 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
 419
 420 <p>CUPS provides two libraries that interface with the different parts of the
 421 printing system. The "cups" library provides all of the common application and
 422 filter functions while the "cupsimage" library provides all of the imaging
 423 functions used in raster printer drivers. The "cups" library functions are
 424 accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
 425 "cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
 426 header.</p>
 427
 428 <h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
 429
 430 <p>The CUPS libraries can be used from any C, C++, or Objective C program.
 431 The method of compiling against the libraries varies depending on the
 432 operating system and installation of CUPS. The following sections show how
 433 to compile a simple program (shown below) in two common environments.</p>
 434
 435 <p>The following simple program lists the available printers on the system:</p>
 436
 437 <pre class="example">
 438 #include &lt;stdio.h&gt;
 439 #include &lt;cups/cups.h&gt;
 440
 441 int main(void)
 442 {
 443   int i;
 444   cups_dest_t *dests, *dest;
 445   int num_dests = cupsGetDests(&amp;dests);
 446
 447   for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
 448   {
 449     if (dest->instance)
 450       printf("%s/%s\n", dest->name, dest->instance);
 451     else
 452       puts(dest->name);
 453   }
 454
 455   return (0);
 456 }
 457 </pre>
 458
 459 <h3><a name="XCODE">Compiling with Xcode</a></h3>
 460
 461 <p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
 462 then select the <var>Standard Tool</var> project type under <var>Command Line
 463 Utility</var>. Click <var>Next</var> and choose a project directory. Click
 464 <var>Next</var> to create the project.</p>
 465
 466 <p>In the project window, double-click on the <var>Targets</var> group and
 467 control-click on the simple target to show the context menu. Choose
 468 <var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
 469 chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
 470 down the file list and select the <var>libcups.dylib</var> file. Click the
 471 <var>Add</var> button in the file chooser and attributes sheets.</p>
 472
 473 <p>In the project window, double-click on the <var>main.c</var> source file.
 474 Replace the template source code with the listing above and save it. Click the
 475 <var>Build and Go</var> button to build the sample program and run it.</p>
 476
 477 <h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
 478
 479 <p>From the command-line, create a file called <var>sample.c</var> using your
 480 favorite editor and then run the following command to compile it with GCC and
 481 run it:</p>
 482
 483 <pre class="command">
 484 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
 485 ./simple
 486 </pre>
 487
 488 <p>The <code>cups-config</code> command provides the compiler flags
 489 ("cups-config --cflags") and libraries ("cups-config --libs") needed for the
 490 local system.</p>
 491
 492 <h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
 493
 494 <p>If you are developing a print filter, driver, or backend, see the
 495 <a href="api-filter.html" target="_top">Filter and Backend Programming</a>
 496 guide. Raster printer driver developers should also read the
 497 <a href="api-raster.html" target="_top">Raster API</a> reference.</p>
 498 </div>
 499 </body>
 500 </html>