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