cups/api-overview.shtml

   1 <!--
   2   "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
   3
   4   Introduction to CUPS programming content for the Common UNIX Printing System
   5   (CUPS).
   6
   7   Copyright 2008 by Apple Inc.
   8
   9   These coded instructions, statements, and computer programs are the
  10   property of Apple Inc. and are protected by Federal copyright
  11   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  12   which should have been included with this file.  If this file is
  13   file is missing or damaged, see the license at "http://www.cups.org/".
  14 -->
  15
  16 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
  17
  18 <p>CUPS provides two libraries that interface with the different parts of the
  19 printing system. The "cups" library provides all of the common application and
  20 filter functions while the "cupsimage" library provides all of the imaging
  21 functions used in raster printer drivers. The "cups" library functions are
  22 accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
  23 "cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
  24 header.</p>
  25
  26 <h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
  27
  28 <p>The CUPS libraries can be used from any C, C++, or Objective C program.
  29 The method of compiling against the libraries varies depending on the
  30 operating system and installation of CUPS. The following sections show how
  31 to compile a simple program (shown below) in two common environments.</p>
  32
  33 <p>The following simple program lists the available printers on the system:</p>
  34
  35 <pre class="example">
  36 #include &lt;stdio.h&gt;
  37 #include &lt;cups/cups.h&gt;
  38
  39 int main(void)
  40 {
  41   int i;
  42   cups_dest_t *dests, *dest;
  43   int num_dests = cupsGetDests(&amp;dests);
  44
  45   for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
  46   {
  47     if (dest->instance)
  48       printf("%s/%s\n", dest->name, dest->instance);
  49     else
  50       puts(dest->name);
  51   }
  52
  53   return (0);
  54 }
  55 </pre>
  56
  57 <h3><a name="XCODE">Compiling with Xcode</a></h3>
  58
  59 <p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
  60 then select the <var>Standard Tool</var> project type under <var>Command Line
  61 Utility</var>. Click <var>Next</var> and choose a project directory. Click
  62 <var>Next</var> to create the project.</p>
  63
  64 <p>In the project window, double-click on the <var>Targets</var> group and
  65 control-click on the simple target to show the context menu. Choose
  66 <var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
  67 chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
  68 down the file list and select the <var>libcups.dylib</var> file. Click the
  69 <var>Add</var> button in the file chooser and attributes sheets.</p>
  70
  71 <p>In the project window, double-click on the <var>main.c</var> source file.
  72 Replace the template source code with the listing above and save it. Click the
  73 <var>Build and Go</var> button to build the sample program and run it.</p>
  74
  75 <h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
  76
  77 <p>From the command-line, create a file called <var>sample.c</var> using your
  78 favorite editor and then run the following command to compile it with GCC and
  79 run it:</p>
  80
  81 <pre class="command">
  82 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
  83 ./simple
  84 </pre>
  85
  86 <p>The <code>cups-config</code> command provides the compiler flags
  87 ("cups-config --cflags") and libraries ("cups-config --libs") needed for the
  88 local system.</p>
  89
  90 <h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
  91
  92 <p>If you are developing a print filter, driver, or backend, see the
  93 <a href="api-filter.html" target="_top">Filter and Backend Programming</a>
  94 guide. Raster printer driver developers should also read the
  95 <a href="api-raster.html" target="_top">Raster API</a> reference.</p>