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