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 CUPS.
 410
 411   Copyright 2008-2011 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>