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