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