doc/help/api-overview.html

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