cups/api-overview.shtml

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