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: inherit;
  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: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
 345
 346   Introduction to CUPS programming header for CUPS.
 347
 348   Copyright 2008-2011 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 <li><a href="#OVERVIEW">Overview</a></li>
 399 <li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
 400         <li><a href="#XCODE">Compiling with Xcode</a></li>
 401         <li><a href="#COMMANDLINE">Compiling with GCC</a></li>
 402 </ul></li>
 403 <li><a href="#WHERETOGO">Where to Go Next</a></li>
 404 </ul>
 405 <!--
 406   "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
 407
 408   Introduction to CUPS programming content for CUPS.
 409
 410   Copyright 2008-2011 by Apple Inc.
 411
 412   These coded instructions, statements, and computer programs are the
 413   property of Apple Inc. and are protected by Federal copyright
 414   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 415   which should have been included with this file.  If this file is
 416   file is missing or damaged, see the license at "http://www.cups.org/".
 417 -->
 418
 419 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
 420
 421 <p>CUPS provides two libraries that interface with the different parts of the
 422 printing system. The "cups" library provides all of the common application and
 423 filter functions while the "cupsimage" library provides all of the imaging
 424 functions used in raster printer drivers. The "cups" library functions are
 425 accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
 426 "cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
 427 header.</p>
 428
 429 <h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
 430
 431 <p>The CUPS libraries can be used from any C, C++, or Objective C program.
 432 The method of compiling against the libraries varies depending on the
 433 operating system and installation of CUPS. The following sections show how
 434 to compile a simple program (shown below) in two common environments.</p>
 435
 436 <p>The following simple program lists the available printers on the system:</p>
 437
 438 <pre class="example">
 439 #include &lt;stdio.h&gt;
 440 #include &lt;cups/cups.h&gt;
 441
 442 int main(void)
 443 {
 444   int i;
 445   cups_dest_t *dests, *dest;
 446   int num_dests = cupsGetDests(&amp;dests);
 447
 448   for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
 449   {
 450     if (dest->instance)
 451       printf("%s/%s\n", dest->name, dest->instance);
 452     else
 453       puts(dest->name);
 454   }
 455
 456   return (0);
 457 }
 458 </pre>
 459
 460 <h3><a name="XCODE">Compiling with Xcode</a></h3>
 461
 462 <p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
 463 then select the <var>Standard Tool</var> project type under <var>Command Line
 464 Utility</var>. Click <var>Next</var> and choose a project directory. Click
 465 <var>Next</var> to create the project.</p>
 466
 467 <p>In the project window, double-click on the <var>Targets</var> group and
 468 control-click on the simple target to show the context menu. Choose
 469 <var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
 470 chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
 471 down the file list and select the <var>libcups.dylib</var> file. Click the
 472 <var>Add</var> button in the file chooser and attributes sheets.</p>
 473
 474 <p>In the project window, double-click on the <var>main.c</var> source file.
 475 Replace the template source code with the listing above and save it. Click the
 476 <var>Build and Go</var> button to build the sample program and run it.</p>
 477
 478 <h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
 479
 480 <p>From the command-line, create a file called <var>sample.c</var> using your
 481 favorite editor and then run the following command to compile it with GCC and
 482 run it:</p>
 483
 484 <pre class="command">
 485 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
 486 ./simple
 487 </pre>
 488
 489 <p>The <code>cups-config</code> command provides the compiler flags
 490 ("cups-config --cflags") and libraries ("cups-config --libs") needed for the
 491 local system.</p>
 492
 493 <h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
 494
 495 <p>If you are developing a print filter, driver, or backend, see the
 496 <a href="api-filter.html" target="_top">Filter and Backend Programming</a>
 497 guide. Raster printer driver developers should also read the
 498 <a href="api-raster.html" target="_top">Raster API</a> reference.</p>
 499 </div>
 500 </body>
 501 </html>