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